# Webhook requests

> The exact format of Emailit webhook requests, from method and headers to the JSON array of events, plus ordering, duplicates and how to respond.

This page describes what arrives at your endpoint: the HTTP request, its headers, the JSON body, and what Emailit expects back. Use it when writing or debugging a webhook handler.

## Request

| Property | Value |
| --- | --- |
| Method | `POST` |
| Body | A JSON array of 1 to 100 events, compact (no extra whitespace) |
| Timeout | 30 seconds |
| Redirects | Not followed. A `3xx` response counts as a failure. |
| Concurrency | One request at a time per webhook. Batches are sent one after another. |
| Latency | Emailit checks for new events every few seconds, so most events arrive within seconds. |

```http
POST /webhooks/emailit HTTP/1.1
Host: acme.com
Content-Type: application/json
User-Agent: Emailit-Webhooks/2.0
X-Emailit-Signature: 7242b580f77ec488f8ac21b57f092e3db61a431694f13074c7b4c85a4dd04be3
X-Emailit-Timestamp: 1790846045
```

## Headers

| Header | Description |
| --- | --- |
| `Content-Type` | Always `application/json`. |
| `User-Agent` | Always `Emailit-Webhooks/2.0`. |
| `X-Emailit-Signature` | Hex-encoded HMAC-SHA256 of `{timestamp}.{raw body}`, keyed with the webhook's full secret (including `whsec_`). See [Request signature](/docs/webhooks/request-signature/). |
| `X-Emailit-Timestamp` | Unix time in seconds when Emailit signed the request. Every attempt, including retries, is signed again with a new timestamp. |

## Body

The body is always a JSON array, even when it contains a single event. Each element has this shape:

| Field | Type | Description |
| --- | --- | --- |
| `event_id` | string | The event's ID, starting with `evt_`. The same event keeps the same ID across retries. Test events start with `evt_test_`. |
| `type` | string | The [event type](/docs/webhooks/event-types/), such as `email.delivered`. |
| `object` | object | The resource the event is about. |
| `data` | object | Contains `object` again. `data.object` and the top-level `object` are identical; read whichever you prefer. |

The fields inside `object` depend on the type. Email status events describe the email; `email.clicked` and `email.loaded` describe the click or load and nest the email; resource events such as `contact.created` describe the resource.

### Example batch

This request carries two events: a delivery and a later click on a link in the same email.

```json
[
  {
    "event_id": "evt_2xGk7Nq1VbD5sR8tLmW3eYhC6aP",
    "type": "email.delivered",
    "object": {
      "id": "em_2xGk7Lr3XcB8pQ1wYzK4dTfG9hJ",
      "object": "email",
      "from": "billing@acme.com",
      "to": "ada@example.com",
      "subject": "Your receipt #1042",
      "status": "delivered",
      "meta": { "order_id": "1042" },
      "updated_at": "2026-10-01T09:14:03.512000+00:00",
      "created_at": "2026-10-01T09:14:01.207000+00:00"
    },
    "data": {
      "object": {
        "id": "em_2xGk7Lr3XcB8pQ1wYzK4dTfG9hJ",
        "object": "email",
        "from": "billing@acme.com",
        "to": "ada@example.com",
        "subject": "Your receipt #1042",
        "status": "delivered",
        "meta": { "order_id": "1042" },
        "updated_at": "2026-10-01T09:14:03.512000+00:00",
        "created_at": "2026-10-01T09:14:01.207000+00:00"
      }
    }
  },
  {
    "event_id": "evt_2xGkC8w2TnF4yR7bMqL1sVdJ6pE",
    "type": "email.clicked",
    "object": {
      "id": "click_2xGkC7v5PmD3xQ9aLnK2rUcH8oW",
      "object": "click",
      "email_id": "em_2xGk7Lr3XcB8pQ1wYzK4dTfG9hJ",
      "email": {
        "id": "em_2xGk7Lr3XcB8pQ1wYzK4dTfG9hJ",
        "rcpt_to": "ada@example.com",
        "mail_from": "billing@acme.com",
        "subject": "Your receipt #1042",
        "created_at": "2026-10-01T09:14:01.207000+00:00",
        "campaign": null,
        "meta": { "order_id": "1042" }
      },
      "link": {
        "id": "link_2xGk7Mb6QwE1zS8cNpT4vXfK3gB",
        "url": "https://acme.com/orders/1042"
      },
      "contact": { "id": "con_2xFh3Ka9LmP2nR6tVwB8cDqY5sZ", "email": "ada@example.com" },
      "ip_address": "203.0.113.24",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X)",
      "created_at": "2026-10-01T09:20:47.884000+00:00"
    },
    "data": {
      "object": {
        "id": "click_2xGkC7v5PmD3xQ9aLnK2rUcH8oW",
        "object": "click",
        "email_id": "em_2xGk7Lr3XcB8pQ1wYzK4dTfG9hJ",
        "email": {
          "id": "em_2xGk7Lr3XcB8pQ1wYzK4dTfG9hJ",
          "rcpt_to": "ada@example.com",
          "mail_from": "billing@acme.com",
          "subject": "Your receipt #1042",
          "created_at": "2026-10-01T09:14:01.207000+00:00",
          "campaign": null,
          "meta": { "order_id": "1042" }
        },
        "link": {
          "id": "link_2xGk7Mb6QwE1zS8cNpT4vXfK3gB",
          "url": "https://acme.com/orders/1042"
        },
        "contact": { "id": "con_2xFh3Ka9LmP2nR6tVwB8cDqY5sZ", "email": "ada@example.com" },
        "ip_address": "203.0.113.24",
        "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X)",
        "created_at": "2026-10-01T09:20:47.884000+00:00"
      }
    }
  }
]
```

Timestamps are ISO 8601 in UTC. `meta` is the metadata you attached when sending, or `null`. `contact` is `null` when the recipient isn't one of your contacts, and `campaign` is `null` for API and SMTP mail.

## Ordering

Within one request, events are ordered oldest first. Across requests there's no ordering guarantee: a batch that failed is retried later while newer events may already have arrived, and a manual retry can resend old events after new ones.

Don't assume arrival order. For email events, use the email's `status` and `updated_at`, and keep the most advanced state you've seen (for example, don't overwrite `clicked` with a late `delivered`). When in doubt, fetch the current state with [Retrieve an email](/docs/api-reference/emails/get/).

## Duplicates

The same event can arrive more than once:

- When your endpoint times out or returns an error after processing part of a batch, the whole batch is retried, including events you already handled.
- When you use **Retry failed** or retry a single request.

Store each `event_id` you've processed, with a unique constraint, and skip events you've seen.

## Responding

| Your response | Result |
| --- | --- |
| Any `2xx` within 30 seconds | Every event in the batch is marked **Delivered**. The response body is ignored. |
| `3xx`, `4xx` or `5xx` | The batch failed and is retried. |
| No response within 30 seconds, connection error, TLS error | The batch failed and is retried. The dashboard shows status code `0`. |

Emailit stores the first 2,000 characters of your response body for failed requests. You can read it on the webhook's **Requests** tab, which makes returning a short error message useful for debugging.

Recommendations:

- **Verify, then acknowledge fast.** Check the signature, put the events on a queue or in a table, and return `200`. Do slow work, such as calling other APIs, in a background job.
- **Return `2xx` for events you ignore.** Otherwise they're retried for days.
- **Return `401` or `403` for a bad signature.** It's retried like any failure, which gives you time to fix a misconfigured secret.

See [Retries and failures](/docs/webhooks/retries-and-failures/) for the retry schedule and what happens when an endpoint keeps failing.

## Related

  - [Request signature](/docs/webhooks/request-signature/)
  - [Event types](/docs/webhooks/event-types/)

---
Source: https://emailit.com/docs/webhooks/webhook-requests/
