Email delivery event webhooks

Webhook endpoints let your systems receive high-deliverability email events from Spotzee instead of polling. Spotzee tracks 27 queue, delivery, and reputation events, records the matching activity on the Contact profile, and can forward each event name with its detail payload to your selected endpoint.

This page only applies to Enterprise customers with Spotzee’s high-deliverability email service enabled. It does not apply to non-Enterprise customers or projects using standard provider delivery.

Webhook endpoint management lives under Settings → Webhook Endpoints at /projects/{projectId}/settings/webhooks and requires the project admin role.

Add an endpoint

Open Settings → Webhook Endpoints

Inside the project, open Settings and select Webhook Endpoints.

Create the endpoint

Choose Add endpoint, then complete:

Name. Recognisable label (for example, analytics-pipeline).
Description. Optional. Useful for documenting what the endpoint is for.
URL. Where Spotzee will POST events. Must be HTTPS.
Events. Pick the event names you want to receive. See the catalogue below.

Save

Save. Spotzee generates a signing secret and shows it once. Copy the secret into your endpoint’s secrets manager. Subsequent reads return the secret in masked form.

Choose events

Choose the events that match the signals your downstream system needs. Each forwarded payload includes the event type, project identifier, timestamp, and event-specific data.

Category	Events	Use for
Queue	`queue.queue-message-authenticated`, `queue.rescheduled`, `queue.quota-exceeded`, `delivery.concurrency-limit-exceeded`	Pipeline observability, capacity planning
Delivery lifecycle	`delivery.attempt-start`, `delivery.attempt-end`, `delivery.completed`	Per-attempt audit trail
Delivery success	`delivery.delivered`	The “this landed” signal
Delivery bounces	`delivery.dsn-perm-fail`, `delivery.dsn-temp-fail`, `delivery.failed`, `delivery.mail-from-rejected`, `delivery.message-rejected`, `delivery.rcpt-to-rejected`, `delivery.rcpt-to-failed`	Bounce classification, list hygiene
Delivery infrastructure	`delivery.mx-lookup-failed`, `delivery.ip-lookup-failed`, `delivery.null-mx`, `delivery.connect-error`, `delivery.greeting-failed`, `delivery.ehlo-rejected`	Routing and connection failures
Encrypted delivery	`delivery.start-tls-error`, `delivery.start-tls-unavailable`, `delivery.implicit-tls-error`	Encrypted handoff failures
Reputation	`incoming-report.abuse-report`, `incoming-report.fraud-report`, `incoming-report.virus-report`	Sender-reputation feedback

You can subscribe to as many events as you like. Keep the list focused if your receiver routes different event types to different systems. For the wire-level format, signing scheme, and API endpoint management, see Webhook conventions.

Payload details

Live delivery webhooks use the same top-level wrapper as other Spotzee webhooks. The data object changes by event type and includes the delivery details available for that event.

{
  "event_type": "delivery.delivered",
  "timestamp": "2026-06-25T13:00:00.000Z",
  "project_id": 42,
  "data": {
    "queueId": "queue-id-from-payload",
    "spanId": "delivery-attempt-id",
    "to": "recipient@example.com",
    "hostname": "recipient-host.example",
    "code": 250,
    "details": "accepted",
    "elapsed": 842
  }
}

Spotzee omits unavailable values and may add extra diagnostic keys over time. Build receivers to ignore fields they do not use.

Detail field	What it tells you
`queueId`	Correlates events that belong to the same message lifecycle.
`spanId`	Correlates events from the same delivery attempt.
`from`, `to`	Sender and recipient addresses involved in the event.
`queueName`	Delivery lane that processed the message, when available.
`hostname`, `domain`	Recipient-side host or domain involved in the event.
`code`, `details`, `reason`, `causedBy`	Response and diagnostic information explaining an acceptance, rejection, or failure.
`size`, `total`	Message size and recipient or attempt counts.
`elapsed`	Duration reported for the event, in milliseconds.
`nextRetry`, `nextDsn`, `expires`	Retry, notification, and expiry times for deferred messages.
`localIp`, `remoteIp`, `remotePort`	Connection endpoint diagnostics for connectivity failures.
`rangeFrom`, `url`, `result`	Report metadata for abuse, fraud, or malware reports.

Common detail fields by event family:

Event family	Detail keys you can receive
Queue and capacity	`queueId`, `from`, `to`, `size`, `nextRetry`, `nextDsn`, `expires`, `id`, `type`
Delivery lifecycle	`queueId`, `spanId`, `queueName`, `from`, `to`, `size`, `total`, `elapsed`
Delivery success	`queueId`, `spanId`, `to`, `hostname`, `code`, `details`, `elapsed`
Bounce and rejection	`queueId`, `spanId`, `to`, `hostname`, `code`, `details`, `reason`, `causedBy`, `nextRetry`, `expires`, `total`
Routing and connection	`queueId`, `spanId`, `domain`, `hostname`, `localIp`, `remoteIp`, `remotePort`, `details`, `causedBy`, `elapsed`
Encrypted delivery	`queueId`, `spanId`, `domain`, `hostname`, `code`, `details`, `causedBy`, `elapsed`
Reputation	`rangeFrom`, `domain`, `hostname`, `url`, `remoteIp`, `total`, `result`, `details`

Event catalogue

The event_type value in the webhook payload matches the names below exactly.

Queue events

Event	When it triggers
`queue.queue-message-authenticated`	The message has been accepted for delivery after Spotzee’s initial sender and message checks.
`queue.rescheduled`	A message delivery attempt has been deferred and scheduled to run again later.
`queue.quota-exceeded`	The send cannot continue because the project’s allocated sending quota has been reached.
`delivery.concurrency-limit-exceeded`	Delivery is paused because the project has reached the allowed number of simultaneous delivery attempts.

Delivery lifecycle events

Event	When it triggers
`delivery.attempt-start`	Spotzee has started an attempt to deliver the message to the recipient’s domain.
`delivery.attempt-end`	A specific delivery attempt has finished, whether it succeeded, failed, or will be retried.
`delivery.completed`	Spotzee has completed the delivery process for the message and no further attempts are pending.

Delivery success event

Event	When it triggers
`delivery.delivered`	The recipient’s mail service accepted the message for delivery to the recipient.

Bounce and rejection events

Event	When it triggers
`delivery.dsn-perm-fail`	A permanent delivery failure was received, so the address should usually be treated as a hard bounce.
`delivery.dsn-temp-fail`	A temporary delivery failure was received, so the message may still be retried before it expires.
`delivery.failed`	Spotzee could not deliver the message after the available attempts or delivery window ended.
`delivery.mail-from-rejected`	The recipient side rejected the sender address during the delivery conversation.
`delivery.message-rejected`	The recipient side rejected the message content or message-level policy during delivery.
`delivery.rcpt-to-rejected`	The recipient side rejected the recipient address before accepting the message.
`delivery.rcpt-to-failed`	Recipient validation failed during the delivery attempt, usually before the message body was accepted.

Routing and connection events

Event	When it triggers
`delivery.mx-lookup-failed`	Spotzee could not resolve the recipient domain’s mail-routing records.
`delivery.ip-lookup-failed`	Spotzee could not resolve the selected recipient host to an IP address.
`delivery.null-mx`	The recipient domain explicitly publishes that it does not accept email.
`delivery.connect-error`	Spotzee could not establish a network connection to the recipient side.
`delivery.greeting-failed`	The recipient side did not provide a usable initial greeting for message delivery.
`delivery.ehlo-rejected`	The recipient side rejected the initial capability negotiation for message delivery.

Encrypted delivery events

Event	When it triggers
`delivery.start-tls-error`	The encrypted delivery upgrade failed after the recipient side offered it.
`delivery.start-tls-unavailable`	The recipient side did not offer the expected encrypted delivery upgrade.
`delivery.implicit-tls-error`	A direct encrypted delivery connection failed before the message could be transferred.

Reputation events

Event	When it triggers
`incoming-report.abuse-report`	Spotzee received an abuse complaint related to a delivered message.
`incoming-report.fraud-report`	Spotzee received a fraud report related to a delivered message or sender identity.
`incoming-report.virus-report`	Spotzee received a malware or virus report related to a delivered message.

Test the endpoint

The test action sends a sample payload to your endpoint. Use it to validate reachability and signature verification before relying on live event traffic.

Open the endpoint

In Settings → Webhook Endpoints, open the row for the endpoint.

Run a test

Use the Send test action. Spotzee posts a sample payload signed with the test-path scheme: X-Spotzee-Signature: sha256=<hex> where the hex is the HMAC-SHA256 of the request body using your endpoint’s signing secret.

Verify the signature

Your endpoint should compute the same HMAC over the request body and compare it to the header value. A match confirms the request came from Spotzee. Reject any request whose signature doesn’t match.

Live event deliveries use the timestamped Spotzee-Signature: t=...,v1=... signing envelope. Test deliveries use X-Spotzee-Signature: sha256=<hex> so you can verify the endpoint from the Spotzee UI.

Rotate the signing secret

Rotate when a secret might have been exposed (committed to source, shared in a chat, leaked in a log).

Open the endpoint

In Settings → Webhook Endpoints, open the row for the endpoint.

Rotate the secret

Use the Rotate secret action. Spotzee generates a new signing secret and shows it once. Copy it into your secrets manager.

Update your verifier

Update your endpoint to use the new secret. Only the new secret is valid after rotation; the old secret stops verifying immediately.

Endpoint status

Endpoints carry one of three statuses:

Status	Meaning
`active`	Endpoint accepts events. The default after creation.
`inactive`	Manually paused by an admin. No events are dispatched.
`disabled`	Auto-disabled by Spotzee after persistent delivery failures. Re-enable manually after fixing the endpoint.

Inactive and disabled endpoints don’t dispatch events but their configuration is preserved. Re-enable to resume.

Next steps

Webhook conventions

The wire-level signing scheme and event payload shape.

Trigger a campaign

Send a campaign and watch enabled delivery events flow into your endpoint.

Manage API keys

Issue project keys for downstream integrations.

Concepts

Brush up on Users, Journeys, Segments, Channels, and Providers.

Get started

Build

Configure

Integrate

Tools

SDKs

API conventions

Recipes

Releases

Email delivery event webhooks

Add an endpoint

Choose events

Payload details

Event catalogue

Queue events

Delivery lifecycle events

Delivery success event

Bounce and rejection events

Routing and connection events

Encrypted delivery events

Reputation events

Test the endpoint

Rotate the signing secret

Endpoint status

Next steps

Webhook conventions

Trigger a campaign

Manage API keys

Concepts

​Add an endpoint

​Choose events

​Payload details

​Event catalogue

​Queue events

​Delivery lifecycle events

​Delivery success event

​Bounce and rejection events

​Routing and connection events

​Encrypted delivery events

​Reputation events

​Test the endpoint

​Rotate the signing secret

​Endpoint status

​Next steps

Webhook conventions

Trigger a campaign

Manage API keys

Concepts

Add an endpoint

Choose events

Payload details

Event catalogue

Queue events

Delivery lifecycle events

Delivery success event

Bounce and rejection events

Routing and connection events

Encrypted delivery events

Reputation events

Test the endpoint

Rotate the signing secret

Endpoint status

Next steps