Sending

Webhooks

Receive delivery, bounce, open, click and unsubscribe events for transactional email, and check the HMAC-SHA256 signature on each one.

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:

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.

  1. Read Signature.Timestamp, Signature.Token and Signature.Signature from the body.
  2. Join the timestamp and the token as text, with nothing between them: "1763380000" + "3f2b...".
  3. 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.
  4. Encode the result as lowercase hex and compare it with Signature.Signature in constant time.
  5. 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 2xx status 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/events or emailgateway.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