Webhook Payload Reference
Every webhook delivery is a POST request with a JSON payload. This page documents the canonical payload structure and the data shape for each event type.
Canonical Payload Structure
All webhook deliveries share this envelope:
json
{
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"created_at": "2026-04-25T10:15:30.123456+00:00",
"event_type": "email_delivered",
"data": { }
}
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Unique identifier for this delivery |
created_at | string (ISO 8601) | Timestamp when the event was dispatched |
event_type | string | One of the supported event types |
data | object | Event-specific payload (see below) |
HTTP Headers
Every delivery includes these headers:
| Header | Example | Description |
|---|---|---|
Content-Type | application/json | Always JSON |
X-Synapse-Signature | sha256=a1b2c3d4... | HMAC-SHA256 signature for verification |
X-Synapse-Event | email_delivered | The event type (same as event_type in the body) |
User-Agent | Synapse-Webhooks/1.0 | Identifies the request as coming from Synapse |
Event Payloads
email_sent
Fired when the email is accepted by the delivery provider for sending.
json
{
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"created_at": "2026-04-25T10:15:30+00:00",
"event_type": "email_sent",
"data": {
"email_log_id": "9a8b7c6d-5e4f-3a2b-1c0d-ef9876543210",
"contact_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
"email": "[email protected]",
"subject": "Welcome to Acme",
"status": "sent"
}
}
email_delivered
Fired when the recipient's mail server confirms delivery.
json
{
"id": "a2b3c4d5-e6f7-8901-bcde-f12345678901",
"created_at": "2026-04-25T10:15:45+00:00",
"event_type": "email_delivered",
"data": {
"email_log_id": "9a8b7c6d-5e4f-3a2b-1c0d-ef9876543210",
"contact_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
"email": "[email protected]",
"subject": "Welcome to Acme",
"status": "delivered"
}
}
email_delivery_delayed
Fired on a temporary delivery delay (soft bounce, busy server). The provider will retry automatically.
json
{
"id": "b3c4d5e6-f789-0123-cdef-234567890abc",
"created_at": "2026-04-25T10:16:00+00:00",
"event_type": "email_delivery_delayed",
"data": {
"email_log_id": "9a8b7c6d-5e4f-3a2b-1c0d-ef9876543210",
"contact_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
"email": "[email protected]",
"subject": "Welcome to Acme",
"status": "delayed"
}
}
email_opened
Fired when the recipient opens the email (pixel tracking).
json
{
"id": "c4d5e6f7-8901-2345-def0-3456789abcde",
"created_at": "2026-04-25T11:30:00+00:00",
"event_type": "email_opened",
"data": {
"email_log_id": "9a8b7c6d-5e4f-3a2b-1c0d-ef9876543210",
"contact_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
"email": "[email protected]",
"subject": "Welcome to Acme",
"status": "opened"
}
}
email_clicked
Fired when the recipient clicks a link in the email.
json
{
"id": "d5e6f789-0123-4567-ef01-456789abcdef",
"created_at": "2026-04-25T11:32:00+00:00",
"event_type": "email_clicked",
"data": {
"email_log_id": "9a8b7c6d-5e4f-3a2b-1c0d-ef9876543210",
"contact_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
"email": "[email protected]",
"subject": "Welcome to Acme",
"status": "clicked"
}
}
email_bounced
Fired when the email bounces (hard or soft bounce).
json
{
"id": "e6f78901-2345-6789-0123-56789abcdef0",
"created_at": "2026-04-25T10:16:05+00:00",
"event_type": "email_bounced",
"data": {
"email_log_id": "9a8b7c6d-5e4f-3a2b-1c0d-ef9876543210",
"contact_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
"email": "[email protected]",
"subject": "Welcome to Acme",
"status": "bounced"
}
}
email_spam_reported
Fired when the recipient marks the email as spam.
json
{
"id": "f7890123-4567-89ab-cdef-6789abcdef01",
"created_at": "2026-04-25T12:00:00+00:00",
"event_type": "email_spam_reported",
"data": {
"email_log_id": "9a8b7c6d-5e4f-3a2b-1c0d-ef9876543210",
"contact_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
"email": "[email protected]",
"subject": "Welcome to Acme",
"status": "spam_reported"
}
}
email_failed
Fired when delivery permanently fails (not retryable).
json
{
"id": "08901234-5678-9abc-def0-789abcdef012",
"created_at": "2026-04-25T10:20:00+00:00",
"event_type": "email_failed",
"data": {
"email_log_id": "9a8b7c6d-5e4f-3a2b-1c0d-ef9876543210",
"contact_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
"email": "[email protected]",
"subject": "Welcome to Acme",
"status": "failed"
}
}
email_suppressed
Fired when the email is suppressed because the contact is on the suppression list.
json
{
"id": "19012345-6789-abcd-ef01-89abcdef0123",
"created_at": "2026-04-25T10:15:31+00:00",
"event_type": "email_suppressed",
"data": {
"email_log_id": "9a8b7c6d-5e4f-3a2b-1c0d-ef9876543210",
"contact_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
"email": "[email protected]",
"subject": "Welcome to Acme",
"status": "suppressed"
}
}
Data Fields Reference
All event payloads share the same data shape:
| Field | Type | Description |
|---|---|---|
email_log_id | string (UUID) | The Synapse email log record ID |
contact_id | string (UUID) | The contact who received the email |
email | string | The recipient's email address |
subject | string | The email subject line |
status | string | The event status (matches the event type) |
Note
Additional fields may be added to the data object in future versions. Design your webhook handler to ignore unknown fields for forward compatibility.