Email Webhooks: Receive Delivery Events and Verify Signatures Securely

Email webhooks send delivery, bounce, complaint and engagement events to your application as they happen, so you can suppress bad addresses, update records and alert your team without polling an API. This guide shows how to build a secure receiving endpoint, verify every signature, handle retries and duplicates, and test the flow.

How webhooks work

When an event occurs, the platform sends an HTTPS POST request with a JSON body to the URL you registered. Your endpoint checks the request, stores the event and replies. If the reply is not a success, the platform tries again later.

1. The event happens. A message is delivered, bounces, is reported as spam or is clicked.
2. The platform sends a POST request. The body is JSON and the request carries a signature header.
3. Your endpoint verifies the signature. Invalid requests are rejected with a 4xx status.
4. Your endpoint stores the event and answers 200. It does this before any slow work.
5. A worker processes the event. It suppresses an address, updates a record or raises an alert.

Common event types

The exact list for your account is in the event reference. See the bounce code guide for what the reasons in bounce events mean.

An example payload

A bounce event could look like this. Field names are illustrative.

{
  "id": "evt_8f2c1a",
  "type": "bounced",
  "created_at": "2026-05-12T09:41:07Z",
  "data": {
    "message_id": "msg_41b7",
    "recipient": "user@example.com",
    "bounce_type": "hard",
    "status": "5.1.1",
    "reason": "mailbox does not exist"
  }
}

Verify the signature

The signature is an HMAC-SHA256 of the raw request body, calculated with the secret you saved when you registered the endpoint. Compute the same value, then compare the two with a constant-time function so timing differences leak nothing.

PHP example

<?php
$secret    = getenv('WEBHOOK_SECRET');
$raw       = file_get_contents('php://input');
$given     = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$expected  = hash_hmac('sha256', $raw, $secret);

if (!hash_equals($expected, $given)) {
    http_response_code(401);
    exit;
}

$event = json_decode($raw, true);
// store $event, then answer quickly
http_response_code(200);

Node.js example

import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/webhooks/mail', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');
  const given = req.get('x-signature') || '';

  const ok = given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
  if (!ok) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString());
  // enqueue event, then answer
  res.sendStatus(200);
});

Handle retries and duplicates

Delivery is at least once, not exactly once. The same event can arrive twice and events can arrive out of order. Design for both.

CREATE TABLE webhook_events (
  event_id    VARCHAR(64) PRIMARY KEY,
  type        VARCHAR(40) NOT NULL,
  payload     JSON NOT NULL,
  received_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  processed   TINYINT(1) DEFAULT 0
);

Security checklist

• HTTPS only: the endpoint must use a valid certificate.
• Verify every request: reject anything without a valid signature before reading the body.
• Check the timestamp: if one is signed, refuse requests older than a few minutes.
• Limit exposure: use a long random path, restrict methods to POST and apply rate limits.
• Keep secrets out of code: store them in environment variables or a secret manager and rotate them on a schedule or after any suspected leak.
• Log safely: record event ids and outcomes, not secrets or full personal data.

Test before you rely on it

Further reading and sources

• RFC 2104: HMAC, keyed hashing for message authentication
• PHP manual: hash_equals
• Node.js documentation: crypto
• Related guides: SMTP settings, ports and authentication and SMTP bounce codes explained.