Webhooks

Set up an endpoint

On the dashboard’s Webhooks page, add the address that should receive events and choose which events it wants. Owners, admins and developers can manage endpoints.

• The address must be https:// on the public internet, on port 443 or 8443 (443 is https’s own: leave the port out). We call no other port, no private or internal address, and follow no redirects.
• Each endpoint has its own signing secret, starting whsec_. It is shown once, when the endpoint is made or its secret is rotated; keep it in your server’s secret settings. Rotating it stops the old secret at once.
• You can turn an endpoint off and on, and resend any delivery from its recent list.

The events

Events are not sent in a guaranteed order, and one can arrive more than once. Use each event’s created_at to order them, and its webhook-id to act on it once.

The payload

Every event is a JSON object with three fields: type, the event’s name; created_at, when it happened (ISO 8601, UTC); and data.

• For an email.* event, data holds the email’s email_id (the id POST /emails answered), from, to, subject, tags and created_at (when we accepted it), plus the fields in the table above.
• For a domain.* event, data holds domain_id, name, status and, for domain.failed, a reason.
• Never the email’s body or attachments: we keep a body only 72 hours, and never send it anywhere else.

{
  "data": {
    "to": [
      "ada@example.com"
    ],
    "from": "Acme <receipts@acme.ng>",
    "tags": [
      {
        "name": "order",
        "value": "1042"
      }
    ],
    "subject": "Your receipt",
    "email_id": "6f1d3a52-2a0e-4f0b-9d55-0c1f2a3b4c5d",
    "created_at": "2026-10-07T09:00:01.208Z"
  },
  "type": "email.delivered",
  "created_at": "2026-10-07T09:00:04.512Z"
}

The request

Each event is one POST with a JSON body, content-type: application/json, user-agent: MyDomainsHub-Mail-Webhooks/1, and the three headers of Standard Webhooks:

On the wire, a delivery looks like this:

POST /hooks/mydomainshub HTTP/1.1
Host: hooks.acme.ng
webhook-id: msg_2f6c1e0b9a8d4c7e8f1a2b3c4d5e6f70
webhook-timestamp: 1791363605
webhook-signature: v1,h9l5IZCd5qvgeyFOrxXqaO5bfylqYxNOyrE+DulGTUE=
content-type: application/json
user-agent: MyDomainsHub-Mail-Webhooks/1
content-length: 289

{"data":{"to":["ada@example.com"],"from":"Acme <receipts@acme.ng>","tags":[{"name":"order","value":"1042"}],"subject":"Your receipt","email_id":"6f1d3a52-2a0e-4f0b-9d55-0c1f2a3b4c5d","created_at":"2026-10-07T09:00:01.208Z"},"type":"email.delivered","created_at":"2026-10-07T09:00:04.512Z"}

Check the signature

Check every request before you trust it:

1. Take the secret after whsec_ and base64-decode it: those bytes are the key.
2. Join webhook-id, webhook-timestamp and the raw body with dots: id.timestamp.body. Use the body exactly as it arrived — JSON parsed and written out again will not match.
3. Sign that with HMAC-SHA256 and the key, and base64 the result.
4. Compare it, in constant time, with each v1, signature in webhook-signature. One match is enough.
5. Refuse a webhook-timestamp more than five minutes from your clock, so a copied request cannot be replayed later.

In Node, with nothing to install:

// Node 18 or later, no packages needed.
import { createHmac, timingSafeEqual } from 'node:crypto'
import { createServer } from 'node:http'

function verifyWebhook(secret, headers, body, now = Date.now()) {
  const id = headers['webhook-id']
  const timestamp = headers['webhook-timestamp']
  const signatures = headers['webhook-signature']
  if (!id || !timestamp || !signatures || !/^\d+$/.test(timestamp)) return false
  // More than five minutes from your clock: refuse it, so a copied request cannot be replayed.
  if (Math.abs(now / 1000 - Number(timestamp)) > 5 * 60) return false
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64')
  const expected = createHmac('sha256', key).update(`${id}.${timestamp}.${body}`).digest()
  // The header can carry several signatures, separated by spaces: one match is enough.
  return signatures.split(' ').some((signature) => {
    const [version, value] = signature.split(',')
    const given = Buffer.from(value ?? '', 'base64')
    return version === 'v1' && given.length === expected.length && timingSafeEqual(given, expected)
  })
}

const handled = new Set() // in production, a table keyed by webhook-id

createServer(async (request, response) => {
  // The raw body, byte for byte: JSON parsed and re-made would not match the signature.
  const chunks = []
  for await (const chunk of request) chunks.push(chunk)
  const body = Buffer.concat(chunks).toString('utf8')
  if (!verifyWebhook(process.env.MDH_WEBHOOK_SECRET, request.headers, body)) {
    response.writeHead(401).end()
    return
  }
  // A retry or a resend carries the same webhook-id: act on each one once.
  const id = request.headers['webhook-id']
  if (!handled.has(id)) {
    handled.add(id)
    const event = JSON.parse(body)
    console.log(event.type, event.data.email_id ?? event.data.domain_id)
  }
  response.writeHead(204).end() // any 2xx, within 10 seconds
}).listen(3000)

To test your own check, use the request above with the secret whsec_TXlEb21haW5zSHViIGV4YW1wbGUga2V5 (an example, not a real one). The signed content is the id, the timestamp and the body joined by dots, and the signature it gives is v1,h9l5IZCd5qvgeyFOrxXqaO5bfylqYxNOyrE+DulGTUE=. Your check will refuse it for its age unless you set your clock to its timestamp.

msg_2f6c1e0b9a8d4c7e8f1a2b3c4d5e6f70.1791363605.{"data":{"to":["ada@example.com"],"from":"Acme <receipts@acme.ng>","tags":[{"name":"order","value":"1042"}],"subject":"Your receipt","email_id":"6f1d3a52-2a0e-4f0b-9d55-0c1f2a3b4c5d","created_at":"2026-10-07T09:00:01.208Z"},"type":"email.delivered","created_at":"2026-10-07T09:00:04.512Z"}

Answers, retries and turning off

• Answer with any 2xx within 10 seconds. Do slow work after you answer. Anything else — a 3xx, 4xx or 5xx, no answer, or a certificate we cannot check — counts as a failure.
• A failed delivery is tried again after 30 seconds, then 2, 8 and 32 minutes, then about 2 hours, then every 6 hours, for 24 hours from when the event happened. After that it is marked failed, and you can still resend it from the dashboard.
• An endpoint that has answered nothing but failures for 3 days, counted from its first failure since its last success, is turned off at its next failure, and what was waiting for it is marked failed. The Webhooks page shows it as off, and the account log records it. Turn it back on there once it is fixed; events that happen while it is off are not kept for it.
• The dashboard shows each delivery’s attempts and the first 500 characters of your answer, so keep secrets out of what you answer.