Webhooks: A Simple Overview for Everyone
What is a Webhook?
Think of a webhook like a text message notification from your email provider. Whenever something important happens—like an email being delivered, opened, or bouncing—Inboxroad can instantly send a notification (the “webhook”) to a website address (your “endpoint”) that you specify.
This allows your software systems to automatically react to email activity in real-time.
Getting Started in 5 Simple Steps
1. Go to Settings → Webhooks and click add webhook 
2. Give your webhook a descriptive Name (e.g., “CRM Updates”) and enter the HTTPS URL of your application.
3. Choose which Events (e.g., “opened,” “clicked”) and which Sending Domains from your account you want to be notified about
Important notes:
– Webhooks are enabled by default when created
– An HMAC secret key is automatically generated
– Copy the key anytime using the respective button
What Kinds of Events Can I Get?
You can get notifications for all major email activities, such as:
Delivered: The email successfully reached the inbox.
{
“kind”: “delivered”,
“sender”: “sender@example.com”,
“recipient”: “user@example.com”,
“message_id”: “<335026fa-0b4d-4fb3-a92c-8193ac2636b8@example.com>”,
“timestamp”: “2025-09-04T10:00:00Z”,
“campaign”: { “id”: “9d76d4b4-660f-422b-9437-282c31506f7f”, “name”: “September campaign” }
Opened: The recipient opened the email.
* Please note: this event will track only if you are sending emails with us, so if your plan includes email or email pro with inboxroad, which allows you to build campaigns
{
“kind”: “open”,
“sender”: “user@sender.com”,
“recipient”: “user@example.com”,
“message_id”: “48b6240d-cd8b-4d45-b4cb-684f99032103”,
“timestamp”: “2025-09-04T10:00:00Z”,
“campaign”: { “id”: “9d76d4b4-660f-422b-9437-282c31506f7f”, “name”: “September campaign” }
Clicked: The recipient clicked a link in the email.
* Please note: this event will track only if you are sending emails with us, so if your plan includes email or email pro with inboxroad, which allows you to build campaigns
{
“kind”: “click”,
“sender”: “user@sender.com”,
“recipient”: “user@example.com”,
“url”: “https://someurl.com”,
“message_id”: “48b6240d-cd8b-4d45-b4cb-684f99032103”,
“timestamp”: “2025-09-04T10:00:00Z”,
“campaign”: { “id”: “9d76d4b4-660f-422b-9437-282c31506f7f”, “name”: “September campaign” }
Bounced: The email could not be delivered (e.g., the email address doesn’t exist).
Bounce (async, remote)
{
“kind”: “bounce”,
“sync_type”: “async”,
“sender”: “sender@example.com”,
“recipient”: “user@example.com”,
“dsn_status”: “4.4.7 (delivery time expired)”,
“bounce_category”: “message-expired”,
“bounce_type”: “expired”,
“message_id”: “<…@example.com>”,
“timestamp”: “2025-09-04T10:00:00Z”
}
Subscription changed
* Please note: this event will track only if you are sending emails with us, so if your plan includes email or email pro with inboxroad, which allows you to build campaigns
{
“kind”: “subscription_changed”,
“change”: “unsubscribe”, (or “resubscribe”)
“sender”: “user@sender.com”,
“recipient”: “user@example.com”,
“message_id”: “59d619ca-d402-4865-a333-d5a5c5cdb30c”,
“timestamp”: “2025-09-04T10:00:00Z”,
“campaign”: { “id”: “9d76d4b4-660f-422b-943″campaign”: { “id”: “9d76d4b4-660f-422b-9437-282c31506f7f”, “name”: “September campaign”}
“contact_list”: { “id”: “59d619ca-d402-4865-a333-d5a5c5cdb30c”, “name”: “Main List” }
}
By default, you’ll get notifications for all events across all your domains, but you can easily customize this.
What Does the Notification Look Like?/Payload Examples
The notification is a small, structured message. Here’s a simplified example for a bounced email:
json
{
“kind”: “bounce”,
“recipient”: “user@example.com”,
“timestamp”: “2025-09-04T10:00:00Z”,
“message_id”: “<…@example.com>”
}
+Delivered example
…
(Your technical team will use the details in these messages to update your database or CRM.)
Keeping Things Secure
We take security seriously. Here are the two ways to ensure the notifications you receive are authentic:
HMAC Signature (Recommended & More Secure)
- How does it work?
We create a unique, secret “fingerprint” for every message using a password (secret) that only you and Inboxroad know. We send this in a header called X-Signature - Why is it best?
It proves the message is from us and that no one tampered with it during delivery.
This requires your developer to write a few lines of code to verify the fingerprint.
You can create custom header when setting up
By default we send X-Signature only. Any API key must be configured via custom headers on the webhook endpoint.
- Downside: Requests without custom headers will be ignored and not processed however this allows you to check if the request is coming from us
- In short: Custom Headers are used to send additional security credentials or special instructions along with the webhook notification to ensure it is accepted and processed by your application.
HMAC Verification Code Examples
Header: X-Signature
Value: Base64(HMAC-SHA256(raw_body, secret))
Python
import hmac, hashlib, base64
def verify_hmac(raw_body: bytes, signature_header: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).digest()
try:
provided = base64.b64decode(signature_header or “”, validate=True)
except Exception:
return False
return hmac.compare_digest(expected, provided)
Js
import crypto from ‘crypto’;
export function verifyHmac(rawBody, signatureHeader, secret) {
const expected = crypto.createHmac(‘sha256’, secret).update(rawBody).digest();
const provided = Buffer.from(signatureHeader || ”, ‘base64’);
return crypto.timingSafeEqual(expected, provided);
}
Security Made Simple
Think of HMAC like a sealed envelope with a wax stamp:
• Only we and you know the secret “wax stamp” pattern
• If the stamp is broken or missing, you know the message was tampered with
• We automatically create this stamp for you – just give the secret to your developer
Troubleshooting Common Issues
Permission Errors (401/403):
Usually a problem with the HMAC signature or API key. Check that the secret is correct.
Server Errors (5xx):
Your website is taking too long to respond or has crashed. Make sure it acknowledges the message quickly and processes the data in the background.
No Events Coming Through:
Check that the webhook is Enabled, the correct events/domains are selected, and that you are actually sending email traffic.
This guide is designed to be clear for all users while providing essential technical information. We can expand it with more specific code examples for different programming languages as needed.
Ready to Start?
1. Talk to your developer about receiving webhook data
2. Set up your webhook using the 5-step guide above
3. Test with a few emails to see it working
4. Contact support if you get stuck!
