MailClickConvert Webhook Overview

Webhooks allow our system to send a JSON array of event data directly to a URL you specify. For example, you can configure a webhook to notify you when an email recipient unsubscribes. You can then process this data on your side to update or remove records from your database.

Important Notes

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

Security Considerations

To secure your webhook endpoint, verify the APISIGNATURE HTTP header included with each POST. This signature is generated using hash_hmac with sha512 on the POST payload, using your Master API Key as the shared secret. See our sample code downloads for implementation examples.

Webhook Event Types

We currently support the following webhook types:

• open — Triggered when an email is opened
• click — Triggered when a link is clicked in an email
• unsubscribe — Triggered when an 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 — Used for system notifications such as list completion (email/SMS), merge completion, SMS 10DLC events, DBL alerts, campaign errors, and list verification job completion.

Type: open

Triggered when an email is opened.

JSON Data Returned

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

Type: click

Triggered when a link in an email is clicked.

JSON Data Returned

[ { "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) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36 Edg/108.0.1462.42", "action": "click" } ]

Type: unsubscribe

Triggered when a recipient unsubscribes.

JSON Data Returned

[ { "requestid": "10", "timestamp": "1670657076", "email": "test@mydomain.com", "ipaddress": "127.0.0.1", "useragent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36 Edg/108.0.1462.42", "action": "unsubscribe" } ]

Type: smtpsoftbounce

Triggered when a soft bounce occurs via the SMTP API.

JSON Data Returned

[ { "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 the SMTP API.

JSON Data Returned

[ { "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 to avoid unnecessary retries.
• Always validate the APISIGNATURE header to confirm authenticity and prevent spoofed requests.
• Log all received events for easier troubleshooting and monitoring of webhook activity.