{
  "event": "click",
  "email": "customer@example.com",
  "campaignUuid": "019ed1ac-30a6-75be-9204-5a66a318922e",
  "timestamp": "2026-10-14T10:34:49+02:00"
}

Batch format (optional)

One POST carries an array of up to 100 events under the events key. Each item has the same fields as the default format. The X-SmartMailer-Event header is batch.

{
  "events": [
    {
      "event": "open",
      "email": "customer@example.com",
      "campaignUuid": "019ed1ac-30a6-75be-9204-5a66a318922e",
      "timestamp": "2026-10-14T10:34:49+02:00"
    },
    {
      "event": "click",
      "email": "other@example.com",
      "campaignUuid": "019ed1ac-30a6-75be-9204-5a66a318922e",
      "timestamp": "2026-10-14T10:34:50+02:00"
    }
  ]
}

Turn on the batch format when creating the webhook with "batch": true. Without it the webhook receives the default format. GET /api/v1/webhooks returns the setting in the batch field.

POST /api/v1/webhooks
{
  "url": "https://example.com/smartmailer-webhook",
  "events": ["open", "click", "unsubscribed"],
  "batch": true
}

Headers and signature

• X-SmartMailer-Event: the event type (open, click, bounce, hardBounce, complaint, unsubscribed), or batch for a batch.
• X-SmartMailer-Signature: hex HMAC-SHA256 of the request body, keyed with the secret returned when the webhook was created.
• Verify the signature over the raw request body and compare in constant time (hash_equals, timingSafeEqual).

Delivery and endpoint outages

• We wait at most 5 seconds for a response. Reply quickly with a 2xx status and move heavy processing to your own queue.
• After 5 failed deliveries in a row (status 4xx or 5xx, connection error, timeout) the webhook is paused for 15 minutes and events from that period are not delivered. The suspendedUntil field in GET /api/v1/webhooks shows when the pause ends. After the pause we try to deliver again.
• Failed deliveries are not retried. Each event is sent at most once.
• Rarely the same event may arrive twice. Deduplicate by event, email and campaignUuid.