Webhooks tell your app what happened to the transactional email it sent. Each sending domain has its own webhooks, with one URL per event.
Events
| Event to register | EventData.Event in the payload |
Sent when |
|---|---|---|
delivery |
delivered |
The receiving server accepted the message |
bounce |
bounced |
The message bounced, or was rejected before it left |
open |
opened |
The recipient opened the message for the first time |
click |
clicked |
The recipient clicked a link for the first time |
unsubscribe |
unsubscribed |
The recipient unsubscribed |
complaint |
not sent yet | You can register a URL for it, but complaint events are not delivered to webhooks yet |
Add a webhook
In the app, open Transactional, pick the domain and open the Webhooks tab. Add a URL for each event you want. The URL must be http or https and must resolve to a public address. Use https.
With the API, either:
- the account API command
emailgateway.addwebhookwithDomainID,EventandWebhookURL(see Transactional (domains and keys)), or - the sender key endpoint below.
curl -X POST https://app.emailmarketer.io/api/v1/webhooks \
-H "Authorization: Bearer $EM_SENDER_KEY" \
-H "Content-Type: application/json" \
-d '{ "Event": "delivered", "WebhookURL": "https://example.com/hooks/email" }'
{ "NewWebhookID": 999 }
POST /api/v1/webhooks accepts both event forms (delivery or delivered, bounce or bounced, and so on). emailgateway.addwebhook accepts only the short form (delivery, bounce, open, click, unsubscribe, complaint).
| Endpoint | Purpose | Parameters |
|---|---|---|
POST /api/v1/webhooks |
Add a webhook to the key’s domain | Event, WebhookURL |
GET /api/v1/webhooks |
List the domain’s webhooks | none |
DELETE /api/v1/webhooks |
Delete a webhook | WebhookID |
Examples:
# List webhooks
curl -G https://app.emailmarketer.io/api/v1/webhooks \
-H "Authorization: Bearer $EM_SENDER_KEY"
# Delete a webhook
curl -X DELETE -G https://app.emailmarketer.io/api/v1/webhooks \
-H "Authorization: Bearer $EM_SENDER_KEY" \
-d WebhookID=999
Payload
Each event is a POST with a JSON body. The body has two parts: the signature and the event.
{
"Signature": {
"Timestamp": 1763380000,
"Token": "3f2b8c1d9e7a4b6c5d0e1f2a3b4c5d6e",
"Signature": "9a1c...e04f"
},
"EventData": {
"Event": "delivered",
"Domain": "acme.com",
"MessageID": "550e8400-e29b-41d4-a716-446655440000",
"To": "jane@example.com"
}
}
MessageID matches the ID that POST /api/v1/email returned.
Fields in EventData
| Event | Fields |
|---|---|
delivered |
Event, Domain, MessageID, To |
bounced after delivery was tried |
Event, EventType (failed), Domain, MessageID, BouncedEmailAddress (EmailAddress, Status, DiagnosticCode), Reason, Code |
bounced before it left |
Event, EventType (rejected-by-mta), Domain, MessageID, To, Subject, Reason |
opened |
Event, Domain, MessageID, To, IPAddress |
clicked |
Event, Domain, MessageID, To, IPAddress, LinkURL |
unsubscribed |
Event, Domain, MessageID, To, IPAddress |
In BouncedEmailAddress, Status holds the diagnostic text from the receiving server and DiagnosticCode holds the status code. Read both if you log bounce reasons.
Verify the signature
Every payload is signed with HMAC-SHA256 using your domain’s signing key. Verify it before you trust the event.
- Read
Signature.Timestamp,Signature.TokenandSignature.Signaturefrom the body. - Join the timestamp and the token as text, with nothing between them:
"1763380000" + "3f2b...". - Compute HMAC-SHA256 of that string, with the signing key as the key. Use the key exactly as shown, as text. Do not hex-decode it.
- Encode the result as lowercase hex and compare it with
Signature.Signaturein constant time. - Reject old timestamps, for example older than five minutes, so a captured request cannot be replayed later.
Find the signing key on the domain’s Webhooks tab, or with emailgateway.getwebhooks. Rotate it with emailgateway.regeneratesigningkey.
The signature covers the timestamp and the token, not the raw body. Do not try to recompute the token yourself.
Node.js
import crypto from 'node:crypto';
import express from 'express';
const SIGNING_KEY = process.env.EM_WEBHOOK_SIGNING_KEY;
const MAX_AGE_SECONDS = 300;
export function verify(body) {
const sig = body?.Signature;
if (!sig || !sig.Timestamp || !sig.Token || !sig.Signature) return false;
const age = Math.abs(Date.now() / 1000 - Number(sig.Timestamp));
if (!Number.isFinite(age) || age > MAX_AGE_SECONDS) return false;
const expected = crypto
.createHmac('sha256', SIGNING_KEY)
.update(String(sig.Timestamp) + String(sig.Token))
.digest('hex');
const a = Buffer.from(expected, 'utf8');
const b = Buffer.from(String(sig.Signature).toLowerCase(), 'utf8');
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
const app = express();
app.post('/hooks/email', express.json(), (req, res) => {
if (!verify(req.body)) return res.sendStatus(401);
const event = req.body.EventData;
// Queue the event for processing, then answer quickly.
console.log(event.Event, event.MessageID);
res.sendStatus(200);
});
app.listen(3000);
Python
import hashlib, hmac, os, time
from flask import Flask, request, abort
SIGNING_KEY = os.environ["EM_WEBHOOK_SIGNING_KEY"]
MAX_AGE_SECONDS = 300
def verify(body: dict) -> bool:
sig = (body or {}).get("Signature") or {}
ts, token, signature = sig.get("Timestamp"), sig.get("Token"), sig.get("Signature")
if not ts or not token or not signature:
return False
try:
if abs(time.time() - int(ts)) > MAX_AGE_SECONDS:
return False
except (TypeError, ValueError):
return False
expected = hmac.new(
SIGNING_KEY.encode(), f"{ts}{token}".encode(), hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, str(signature).lower())
app = Flask(__name__)
@app.post("/hooks/email")
def email_hook():
body = request.get_json(silent=True)
if not verify(body):
abort(401)
event = body["EventData"]
# Queue the event for processing, then answer quickly.
print(event["Event"], event["MessageID"])
return "", 200
Respond quickly
- Any
2xxstatus counts as delivered. Redirects are followed. - Answer fast and do the work in a background job. Slow responses time out and count as failed.
- Failed deliveries are not retried. If your endpoint was down, read the missed events from the event log with
GET /api/v1/eventsoremailgateway.getevents(see Transactional (domains and keys)). - Opens and clicks are sent for the first open and the first click of each message.
Test a webhook
emailgateway.testwebhook with DomainID and WebhookID sends a signed sample and returns Delivered and ResponseCode. The sample is signed the same way as a real event, so it tests your signature check. Its EventData uses a different, lowercase layout (event, test: true, recipient, message.headers), so do not use it to test how you parse real events.
curl https://app.emailmarketer.io/api.php \
-d Command=emailgateway.testwebhook \
-d APIKey="$EM_API_KEY" \
-d DomainID=12 \
-d WebhookID=999