Webhook Basics

Webhooks allow notifications by posting (POST) a JSON array of event data to a URL of your choice. For example, you can receive a webhook when a recipient unsubscribes from an email, allowing you to update or remove the address from your database.

General Notes

• Batch size: Each webhook payload contains a maximum of 100 records per POST.
• Response status: Your endpoint must return HTTP status 200 to indicate successful receipt. Any other status will be treated as a failure.
• Retry policy: Failed deliveries are retried up to five times using the following intervals: 5 minutes, 1 hour, 3 hours, 12 hours, and 24 hours after the initial attempt.
• Webhook disabling: Your webhook will be disabled if there are 100 consecutive failures.
• The timestamp field is a UNIX timestamp in CST (Central Standard Time).
• The listmetadata field (optional) contains a JSON object of all columns from your list for the associated email record. To include this, enable "Include Full List Column Data" when setting up your webhook.

Security Best Practice

Supported Webhook Types

• open — Triggered when an email is opened
• click — Triggered when a link is clicked in an email
• unsubscribe — Triggered when an email unsubscribe event occurs
• smtpopen — Triggered when an email is opened via SMTP API
• smtpclick — Triggered when a link is clicked in an email via SMTP API
• smtphardbounce — Triggered when a hard bounce occurs via SMTP API
• smtpsoftbounce — Triggered when a soft bounce occurs via SMTP API
• notification — Notifies for different events in the system. Such as list completion for email/SMS, merging list completion, SMS 10dlc events, DBL alerts, campaign error alerts, list verification job completion.

Webhook Data Examples

For when an email is opened

For when a link is clicked in an email

For when an email unsubscribe happens on the account

If using the SMTP API occurs when there is a soft bounce

If using the SMTP API occurs when there is a hard bounce

Implementation Tips

• Ensure your server responds quickly with HTTP 200 so webhook retries are not triggered.
• Always validate the APISIGNATURE for authenticity to prevent spoofed requests.
• Consider logging all received events for troubleshooting any delivery or processing issues.