Webhook Requests

When an event occurs, Emailit sends an HTTP POST request to your configured webhook URL. This page describes the request format, headers, and delivery behavior.

Request format

All webhook requests are sent as POST requests with a JSON body:

• Method: POST
• Content-Type: application/json
• Timeout: 30 seconds

Headers

Each webhook request includes the following headers:

Request body

The request body contains the event payload as JSON:

{
  "event_id": "evt_2bH7kNwP5mQaV1sXgIdKe6pZr",
  "type": "email.delivered",
  "data": {
    "object": {
      "id": "em_4yM2nTvR8oPcX3uZiKeLg7sB",
      "object": "email",
      ...
    }
  }
}

Expected response

Your endpoint should return a 2xx status code (e.g. 200, 201, 204) to acknowledge receipt. Any other status code is treated as a failure.

Retry policy

If your endpoint does not respond with a 2xx status code within 30 seconds, Emailit will retry delivery with the following schedule:

After attempt 6 (7 total attempts), the webhook is automatically disabled. You can re-enable it from the Emailit dashboard.

Ordering

Webhook events are delivered in near real-time but are not guaranteed to arrive in order. Use the event_id and timestamps within the event payload to handle ordering in your application.

IP addresses

Webhook requests are sent from Emailit’s infrastructure. If you need to allowlist IPs, contact support for the current list of outbound IP addresses.

Best practices

• Respond quickly — Process the webhook asynchronously and return a 2xx immediately. Do heavy processing in a background job.
• Handle duplicates — Use event_id to deduplicate events. The same event may be delivered more than once during retries.
• Verify signatures — Always validate the X-Emailit-Signature header to ensure the request came from Emailit. See Request Signature.