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

# Webhooks

Webhooks let Esendex push events — such as delivery reports and inbound messages — to an HTTPS endpoint you control, instead of you polling the API.

## Set up a subscription

### Discover the available events

[Get available events](/api-reference/webhook-events/get-available-events) returns every event type you can subscribe to, with a description of each.

### Subscribe a callback URL

Create a subscription for an event type with [Create subscription (v3)](/api-reference/webhook-subscriptions/create-subscription-v-3):

```bash
curl -X POST http://gateway-api.e97e9e55a5d242f9a139.uksouth.aksapp.io/v3/webhooks/subscriptions \
  -H "X-API-Key: $ESENDEX_API_KEY" \
  -H "AccountReference: EX0000000" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "<event-type>",
    "contactEmail": "dev-team@example.com",
    "callbacks": [
      { "url": "https://example.com/webhooks/esendex", "optionalNotes": "Production handler" }
    ]
  }'
```

To migrate many subscriptions at once, use [Bulk import subscriptions](/api-reference/webhook-subscriptions/bulk-import-subscriptions).

### Respond quickly

Return a `2xx` response as soon as you've received the event, and do any heavy processing asynchronously.

## Secure your endpoint

#### Callback authentication

Configure credentials that Esendex sends when calling your endpoint with [Update callback authentication](/api-reference/webhook-authentication/update-callback-authentication), and choose which methods are allowed with [Update authentication methods](/api-reference/webhook-authentication/update-authentication-methods).

#### Content signing

Enable payload signing with [Update content signing settings](/api-reference/webhook-signing/update-content-signing-settings) and create keys with [Generate signing key](/api-reference/webhook-signing/generate-signing-key). Verify the signature on every request before trusting its contents.