Skip to navigation
Guides

Webhooks

Receive delivery reports and inbound messages in real time

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

1

Discover the available events

Get available events returns every event type you can subscribe to, with a description of each.

2

Subscribe a callback URL

Create a subscription for an event type with Create subscription (v3):

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.

3

Respond quickly

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

Secure your endpoint

Configure credentials that Esendex sends when calling your endpoint with Update callback authentication, and choose which methods are allowed with Update authentication methods.

Enable payload signing with Update content signing settings and create keys with Generate signing key. Verify the signature on every request before trusting its contents.