Webhooks

Estimated time to read: 4 minutes

Webhooks allow your application to receive real-time notifications about email events. Use this feature to keep your systems in sync with your email activity—whether you want to log deliveries, track engagement, or handle failures proactively.

How to Set Up a Webhook

Webhook Name

Enter a name for this webhook. This name is used for identification in your dashboard. Choose something descriptive like "Marketing Emails Tracking" or "Transactional Mail Delivery Events".

Endpoint URL

Provide the URL where the events should be sent (e.g., https://yourdomain.com/webhooks/email-events).

Make sure your endpoint is publicly accessible and ready to accept POST requests with JSON payloads.

Select Events to Send

Choose the types of events you want to be notified about. You can select one or more from the following:

Event	Description	Type values
Message Reception	Triggered when an email is received by our system and queued for delivery.	message.reception
Message Delivered	Sent when an email has been successfully delivered to the recipient.	message.delivered
Message Deferred	Indicates a temporary delivery delay (e.g., recipient's server is down). Retry attempts will be made.	message.transient_error
Message Delivery Failed	Triggered when delivery fails permanently and all retries have been exhausted.	message.failed
Message Bounced	Sent when a bounce is received from the recipient's mail server. May happen even after previous success. Read this if you want to receive the Out-Of-Band bounce messages via email.	message.bounced
Message Opened	Fired when the recipient opens the email (requires open tracking to be enabled).	message.opened
Message Link Clicked	Sent when a recipient clicks on a link in the email (requires click tracking).	message.clicked
Message Suppressed	Sent when delivery is skipped due to the recipient being on a suppression list.	message.suppressed
Suppression Created	Triggered when a suppression is added (e.g., due to repeated failures or manual action).	suppression.created
DNS Error	Indicates issues with DNS configuration (e.g., missing or invalid SPF/DKIM). Future emails will be rejected until resolved.	domain.dns_error

Save Webhook

Click Create Webhook to save and activate your webhook.

Webhooks payload structure

{
    "type": "entity.event",
    "timestamp": "ISO_8601_time",
    "data": {
       // data specific to the event `type`
    }
}

The payload for message webhook events (e.g. any event with a type that starts with message.) will follow this format:

{
    "type": "message.reception",
    "timestamp": "2025-05-06T09:49:16.687031577Z",
    "data": {
        "account_id": "4cdd7bdd-294e-4762-892f-83d40abf5a87",
        "event": "on_reception",
        "from": "info@example.com",
        "recipient": "someone@example.com",
        "subject": "Sample email for testing webhooks",
        "message_id_header": "message-id-header",
        "id": "seseu-message-id"
    }
}

The payload for suppression.created webhook event has the following structure:

{
    "type": "suppression.created",
    "timestamp": "2024-05-06T12:57:06.451529527Z",
    "data": {
        "account_id": "4cdd7bdd-294e-4762-892f-83d40abf5a87",
        "recipient": "someone@example.com",
        "created_at": "2025-05-06T12:57:06.451529617Z",
        "expires_at": "2025-06-05T14:57:06.451529707+02:00",
        "reason": "Too many hard bounces",
        "sending_domain": "your-domain.com"
    }
}

The payload for domain.dns_error webhook event has the following structure:

{
    "type": "domain.dns_error",
    "timestamp": "2024-05-06T12:59:46.404433272Z",
    "data": {
        "domain": "example.com",
        "account_id": "4cdd7bdd-294e-4762-892f-83d40abf5a87",
        "spf_valid": false,
        "dkim_valid": false,
        "dmarc_valid": false,
        "dns_last_checked_at": "2025-05-06T12:59:46.404433312Z"
    }
}

Testing Webhooks

You can test a Webhook by clicking the How to Set Up a Webhook button. If you don't have your own backend endpoint ready yet, or if you'd like to test your webhook configuration before going live, we recommend using PiRequestBin. It's a free, developer-friendly tool for capturing and inspecting HTTP requests.

Securing your Webhooks

To ensure your webhook endpoint only accepts valid requests from our system, we include cryptographic headers that let you verify the authenticity and integrity of each request.

Signature Verification

Every webhook request includes the following headers:

Header	Description
webhook-id	A unique ID for the webhook event. Useful for logging and deduplication.
webhook-timestamp	The Unix timestamp (in seconds) when the event was generated. Helps prevent replay attacks.
webhook-signature	The signature of the webhook payload. You can use the Webhook Secret to verify this signature.

To learn more about verifying the webhook signature please refer to the Verifying Webhook Authenticity section of the Standard Webhooks specification.

Receiving Delivery Status Notifications

We support receiving Delivery Status Notifications for bounced email. When enabled, Transactional Email Service will send Delivery Status Notifications (DSNs) for bounced emails. This feature can be enabled account wide and on the domain level.

Enabling delivery of DSNs

Within your account head over to the Account Settings page, enable Send DSNs for bounced emails and add a global DSN recipient.

Configuring a DSN recipient per domain

After you have enabled delivery of DSN's in your Account Settings you will be able to configure a DSN recipient per domain. Within your account head over to the Domains page and click Settings. Within the Domain Settings popup add a DSN Recipient and click Save Changes.