> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ntropy.com/webhooks/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ntropy.com/_mcp/server.

# Webhooks

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](./api/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](#events) to receive notifications on. There's a limit of 10 webhooks per organization.

<EndpointRequestSnippet endpoint="POST /v3/webhooks" />
<Accordion title="See the full raw output">
    <EndpointResponseSnippet endpoint="POST /v3/webhooks" />
</Accordion>

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

```json
{
    "event_id": "bab90a5e-1321-...",    # unique identifier
    "event_type": "batches.completed",  # the event that occurred
    "data": {},                         # the event payload
}
```

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

<CodeBlocks>

**`SDK`**

```python title="SDK"
from ntropy_sdk import SDK

sdk = SDK("cd1H...Wmhl" )
sdk.webhooks.patch(id="e94a150d-40af-4e96-8aa7-2948a6b4d8d3", enabled=True)
```

**`cURL`**

```bash title="cURL"
curl -X "PATCH" \
    "https://api.ntropy.com/v3/webhooks/e94a150d-40af-4e96-8aa7-2948a6b4d8d3" \
    -H "Accept: application/json" \
    -H "X-API-KEY: cd1H...Wmhl"
    -d '{
        "enabled": true
    }]'
```
</CodeBlocks>

# 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:

| Event Type                | Description                                    |
|---------------------------|------------------------------------------------
| bank_statements.completed | Bank statement has finished processing         |
| bank_statements.error     | Bank statement encountered an error processing |
| batches.completed         | Batch has finished processing                  |
| batches.error             | Batch encountered an error processing          |
| reports.resolved          | Report has been resolved                       |
| reports.rejected          | Report was rejected, check `rejection_reason`  |
| reports.pending           | Report is being investigated                   |




----------------------------------------------------------------------------------------------------