Reference
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. |
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: 1790846045Headers
| 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. |
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, 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.
[
{
"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.
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
2xxfor events you ignore. Otherwise they’re retried for days. - Return
401or403for a bad signature. It’s retried like any failure, which gives you time to fix a misconfigured secret.
See Retries and failures for the retry schedule and what happens when an endpoint keeps failing.