The Webhooks API allows you to receive realtime events about changes in other API resources. It eliminates the need for polling, reducing unnecessary API calls and resource utilization, allowing you to remain under the rate limits.

Create a webhook

To create a webhook, you can use the API or the SDK as your preferred method. A webhook requires a url and a set of events to receive notifications on. There’s a limit of 10 webhooks per organization.

Webhook handling

When an event occurs, Ntropy will make a POST request to the url of the webhook. If you specified a token when creating the webhook, this string will be included in the X-Ntropy-Token header.

The webhook call has a timeout limit of 10 seconds, so any busy processing of the event should be deferred. Responses with 2xx as status code are considered as successful.

The body of the POST request will have the following schema.

1
{
2
    "event_id": "bab90a5e-1321-...",   # unique identifier
3
    "event_type": "batches.finished",  # the event that occurred
4
    "data": {},                        # the event payload
5
}

The data field of the webhook request will follow the same schema as the resource the event corresponds to. For example, in a batches.finished event, the data field will contain a Batch object, the same schema as the /v3/batches/{id} endpoint.

Retry policy

If a non-2xx response is received, a timeout of 10 seconds is exceeded, or the request fails, the request will be retried with the same event_id for up to 24 hours. Occasionally the webhook might be called multiple times even after a successful response is received. We recommend that you log the list of already processed event_id to not handle an event twice.

Re-enabling webhooks

Webhooks have a limit of non-2xx consecutive responses that they can receive before being disabled. You may re-enable a webhook by setting the enabled attribute to True.

1
from ntropy_sdk import SDK
2
3
sdk = SDK("cd1H...Wmhl" )
4
sdk.webhooks.patch(id="e94a150d-40af-4e96-8aa7-2948a6b4d8d3", enabled=True)

Events

In the previous example we created a webhook that will get notified on completion or failed runs of batches and bank statements. The available list of events is below: