About webhooks

Webhooks are a common means for applications to communicate and share real-time data. In today's landscape, standalone applications that encompass all functionalities are rare. Typically, we work with various specialized apps and systems designed for specific tasks, and these systems must be able to exchange information seamlessly. This is where webhooks play a pivotal role.

A webhook is an automated message sent from one system to another once specific criteria are met. In the case of Naxai, this criteria often involves triggering an event.

At its essence, a webhook is an event-driven approach that enables two separate systems to take action based on real-time data transmission. Within this message, some instructions guide the receiving system on when and how to execute a particular task. Consequently, webhooks offer a more dynamic and adaptable means to access data and programmatic capabilities, allowing you to establish customer journeys that streamline processes.

Each webhook sends a configurable HTTPS request carrying Naxai data in its payload to these 3rd-party applications' application programming interfaces (APIs).

The following key attributes can be configured for each webhook:

• The URL of the 3rd-party application,
• An optional but recommended authentication method
• The type of events to subscribe for (Email, SMS, Survey, Contact)
• The name of events you want to subscribe to (E.g. receiving only undelivered emails)
• The list of API credentials (application) or Surveys you want to subscribe for.

📘

Security

For security purpose, only HTTPS is supported and TLS minimum version must be 1.2

Endpoints are automatically deactivated when not filling this requirement.

Creating webhook

From the Naxai dashboard, go to Integrations -> Webhooks, and select Add Webhook.

1. Provide a friendly name to your webhook endpoint
2. Type in the webhook URL endpoint (only HTTPS TLS 1.2 or greater is supported)
3. Select the authentication required by your webhook endpoint :
   1. No Auth: for no authentication (not recommended)
   2. Basic Auth: for basic authentication with username and password
   3. Header: when a header key and value are passed (e.g. X-API-KEY)
   4. OAuth 2.0: when using an OAuth authorization token
4. Select one or more Event Types to receive webhooks from particular services or resources:
   1. e.g. SMS, Email, Survey,...
5. Select one or more Event Names to receive only events from one action
   1. e.g. email.clicked.v1 , survey.completed.v1 ...
6. Filter based on API credentials or Survey Id
   1. e.g. using API Credentials created for a specific application or a Survey Id (if applicable)

Disabling or enabling webhooks

You can manually disable and re-enable a webhook by clicking the Active checkbox on the webhook details page.

Creating programmatically webhooks

You can configure webhook endpoints via the API to be notified about events that happen in Naxai.

Most users configure webhooks from the dashboard, which provides a user interface for registering and testing your webhook endpoints.

Webhook retry policies

❗️

Automatic deactivation of webhooks

Your webhooks are automatically deactivated if the TLS version is lower than 1.2 or if the number of failed requests is greater than 10% during the last hour (provided there have been 100 requests minimum)

Webhooks function by having Naxai's servers send requests to an external endpoint, and syntax and other factors can potentially cause errors. Webhooks might also fail due to problems such as expired API keys, reaching rate limits, or unexpected server errors.

If your webhook fails to send, an email is sent to the account owners depending on several factors.

When retrying, Naxai will make up to six retries using the following sleep period before each new attempt: 5 min, 10min, 15min, 30min, 60min, 240min.

Each webhook is allowed3 seconds before it times out, generating an error and a retry.

A webhook request will be considered successful if Naxai receives an HTTP response status code in the range of 200 to 399.
Any unsuccessful response codes within the 400 to 599 range will not be retried except for the following list:

• 408, 409, 429, or 5xx response

IP whitelisting

When Naxai sends a webhook, it initiates network requests to either our customers' or third-party servers. By implementing IP whitelisting, you can authenticate the source of Webhook requests, ensure they originate from Naxai, and enhance security.