Hypermail Webhook Documentation

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.
Retry policy: Failed deliveries are retried up to 5 times at intervals: 5 min, 1 hr, 3 hrs, 12 hrs, and 24 hrs.
Webhook disabling: Your webhook will be disabled after 100 consecutive failures.
Timestamp: The timestamp field is a UNIX timestamp in CST (Central Standard Time).
List metadata: Optional JSON object with all columns from your list. Enable "Include Full List Column Data" when setting up.

Security Best Practice

To secure your webhook endpoint, verify the APISIGNATURE HTTP header included with each POST.

The signature is generated using hash_hmac with sha512 on the POST payload and your Master API Key as the shared secret.

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 via SMTP API

smtphardbounce

Triggered when a hard bounce occurs via SMTP API

smtpsoftbounce

Triggered when a soft bounce occurs via SMTP API

notification

System events: list completion, DBL alerts, campaign errors, etc.

Webhook Data Examples

Type: open

Triggered when an email is opened

[
  {
    "requestid": "13",
    "timestamp": "1670694746",
    "email": "sales@test.com",
    "ipaddress": "127.0.0.1",
    "useragent": "Mozilla/4.0 (compatible; ms-office; MSOffice 16)",
    "action": "open",
    "campaignid": "123436",
    "listid": "63534"
  }
]

Type: click

Triggered when a link is clicked in an email

[
  {
    "requestid": "5",
    "timestamp": "1670646495",
    "email": "sales@test.com",
    "ipaddress": "127.0.0.1",
    "link": "https://google.com",
    "useragent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
    "action": "click",
    "campaignid": "434254",
    "listid": "111143"
  }
]

Type: unsubscribe

Triggered when an email unsubscribe happens

[
  {
    "requestid": "10",
    "timestamp": "1670657076",
    "email": "test@test.com",
    "ipaddress": "127.0.0.1",
    "useragent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
    "action": "unsubscribe",
    "campaignid": "434254",
    "listid": "111143"
  }
]

Type: smtpsoftbounce

Triggered when a soft bounce occurs via SMTP API

[
  {
    "requestid": "577880",
    "timestamp": "1753408476",
    "email": "random2@test.com",
    "metadata": "",
    "emailstatus": "Timed Out",
    "debugreason": "Connect timed out.",
    "action": "smtpsoftbounce"
  }
]

Type: smtphardbounce

Triggered when a hard bounce occurs via SMTP API

[
  {
    "requestid": "577881",
    "timestamp": "1753408476",
    "email": "badrandom2@test2.com",
    "metadata": "",
    "emailstatus": "Address does not exist",
    "debugreason": "Requested action not taken: mailbox unavailable or not local.",
    "action": "smtphardbounce"
  }
]

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.