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, Call)
• The name of events you want to subscribe to (E.g. receiving only undelivered emails)
• The list of API credentials (application) you want to subscribe for.
• The emails to notify when the webhook is automatically deactivated.

📘

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,...

5. Select one or more Event Names to receive only events from one action

   1. e.g. email.clicked.v1 , sms.incoming.v1 ...

6. Filter based on API credentials

   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 Message Handling

Returning anything other than 2XX or 3XX from a webhook is considered a delivery failure.

You must be mindful that sending messages at high rates will trigger webhook notifications at high rates, and you must design your code to handle notifications at the expected rate.
It is important for you to consider situations that may cause failure responses - including 500 responses from your web container, timeouts, or upstream failures.

Things to consider include:

• Verify that your DDoS protections are configured to handle the expected rate of webhook notifications.
• Confirm that resources such as database connection pools don't run out, causing timeouts or 500 responses.

You should design your systems so that the processing of webhook events occurs asynchronously and doesn't prevent the webhook from returning a success code (2XX and 3XX).

Correct Handling of Webhook Messages

✅ Webhook callback is sent in queue without sync operations, database access, ...

sequenceDiagram
    participant Naxai@{ "alias": "Naxai Webhook" }
    participant Customer@{ "alias": "Auth Service" }
    participant QueueForDelivery@{ "type": "queue", "alias": "Queue For Delivery" }
    participant MessageConsumer@{"alias": "Queue For Delivery" }
    Naxai->>Customer: Webhook Callback
		activate Customer
    Customer-->>QueueForDelivery: Insert in queue
    QueueForDelivery-->>MessageConsumer: Async Delivery
    Customer->>Naxai: 200 OK
		deactivate Customer

Incorrect Handling of Webhook Messages

❌ Avoid heavy operations and/or database access to limit potential errors and downtime.

sequenceDiagram
    participant Naxai@{"alias": "Naxai Webhook"}
    participant Customer@{ "alias": "Auth Service" }
    participant Database@{"type":"database", "alias": "Database Operations" }
    participant Operations@{"type":"collections", "alias": "sync operations" }


    Naxai->>Customer: Webhook Callback
    activate Customer
    Customer->>Database: Database operations
    Customer->>Operations: sync message delivery
    
    Customer->>Naxai: 200 OK
    deactivate Customer

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 24 hours (with at least 100 requests)

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 specified email addresses 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.