Copy page

Webhooks

Using webhooks

A webhook sends an HTTP POST to your URL each time an event happens in your account: an email bounces, a contact unsubscribes, a campaign is scheduled. This guide covers creating and managing webhooks, the payload your URL receives, checking that a delivery comes from the platform, and the three classes of events.

• Event catalog: every event you can subscribe to, and when it fires.
• Compliance events: the exact payloads of bounces, spam complaints, unsubscribes, and refused or failed sends.

Creating a webhook

A webhook subscribes one URL to one event. To receive several events, create one webhook per event; they can share a URL.

Code
curl --request POST \
  --url 'https://api.cakemail.dev/webhooks' \
  --header 'Authorization: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "event": "Email.Bounced",
    "url": "https://hooks.example.com/platform-events",
    "rate_limit": 10,
    "rate_limit_period": "second"
  }'

The response (201) returns the webhook:

Code
{
  "id": "<webhook_id>",
  "data": {
    "id": "<webhook_id>",
    "status": "active",
    "event": "Email.Bounced",
    "url": "https://hooks.example.com/platform-events",
    "archived_at": null,
    "rate_limit": 10,
    "rate_limit_period": "second"
  }
}

Sub-accounts. Webhook requests act on the account of the access token. A partner or an organization can act on a sub-account by adding ?account_id=<account_id> to any webhook request. That webhook then receives the sub-account's events.

Access tokens. With a personal access token, listing and showing webhooks needs the webhooks:read scope, and creating or changing them needs webhooks:write.

Errors. Error responses have the form {"detail": [{"msg": "…", "type": "…"}]}.

See Create a webhook in the API reference for every field.

Managing webhooks

Receiving events

Each delivery is a POST with a JSON body, a Content-Type: application/json header and an x-signature header (see Securing your webhooks).

The payload envelope

Every event has the same envelope. This is a campaign bounce:

Code
{
  "id": "570bfeff-8a80-5f41-bb57-f2f343e49381",
  "event": "Email.Bounced",
  "account_id": 1234,
  "account_lineage": null,
  "ip": "192.0.2.20",
  "user": {
    "id": null,
    "email": null,
    "account_id": null
  },
  "created_on": 1790431393,
  "data": {
    "bounce": {
      "id": null,
      "dsn_message": "smtp; 550 5.1.1 <jane@example.com>: Recipient address rejected: User unknown",
      "source_ip": "192.0.2.10",
      "category": "bounce_hb"
    },
    "campaign": {
      "type": "campaign",
      "id": 4321,
      "name": "September newsletter"
    },
    "context": {
      "timestamp": null,
      "user_agent": null,
      "ip": null
    },
    "contact": {
      "id": 5678,
      "email": "jane@example.com",
      "status": null
    },
    "list": {
      "id": 111,
      "name": "Newsletter subscribers"
    },
    "segment": {
      "id": null,
      "name": null,
      "query": null
    }
  }
}

Handling deliveries

• Answer with a 2xx status quickly, and do the work afterwards.
• The same event can arrive more than once. Deduplicate on id.
• Events can arrive in any order. When data.event_time or data.context.timestamp is present, use it to order them.
• A webhook's rate_limit caps how fast deliveries reach your URL.

Securing your webhooks

The x-signature header of each delivery is the HMAC-SHA256 of the raw request body, keyed with your account's signing key, written as lowercase hexadecimal. Compute it and compare: a match proves that the platform sent this exact body.

1. Get the signing key. GET /webhooks/{webhook_id} returns it in signature.key. An account has one key, shared by all its webhooks.

   Code
   curl --request GET \
     --url 'https://api.cakemail.dev/webhooks/<webhook_id>' \
     --header 'Authorization: Bearer <access token>'

   Code
   {
     "id": "<webhook_id>",
     "signature": { "key": "<signing key>", "hash_function": "sha256" },
     "data": {
       "id": "<webhook_id>",
       "status": "active",
       "event": "Email.Bounced",
       "url": "https://hooks.example.com/platform-events",
       "archived_at": null,
       "rate_limit": 10,
       "rate_limit_period": "second"
     }
   }

2. Verify the body exactly as received, before parsing it. Parsing and re-serializing the JSON changes the bytes, and the signature no longer matches.

Node.js:

Code
import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body exactly as received (a Buffer or a string), before any JSON parsing.
// signature: the x-signature header. signingKey: signature.key from GET /webhooks/{webhook_id}.
export function isValidSignature(rawBody, signature, signingKey) {
  const expected = Buffer.from(createHmac("sha256", signingKey).update(rawBody).digest("hex"));
  const received = Buffer.from(String(signature ?? ""));
  return received.length === expected.length && timingSafeEqual(received, expected);
}

With Express, read the raw body:

Code
import express from "express";
import { isValidSignature } from "./verify.mjs";

const app = express();

app.post("/platform-events", express.raw({ type: "application/json" }), (req, res) => {
  if (!isValidSignature(req.body, req.get("x-signature"), process.env.WEBHOOK_SIGNING_KEY)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body);
  // Skip event.id if you've seen it, queue the work, and answer right away.
  res.sendStatus(204);
});

Python:

Code
import hashlib
import hmac


def is_valid_signature(raw_body: bytes, signature: str, signing_key: str) -> bool:
    """raw_body: the request body exactly as received, before any JSON parsing.
    signature: the x-signature header. signing_key: signature.key from GET /webhooks/{webhook_id}."""
    expected = hmac.new(signing_key.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected.encode("utf-8"), (signature or "").encode("utf-8"))

With Flask:

Code
import os

from flask import Flask, abort, request

from verify import is_valid_signature

app = Flask(__name__)


@app.post("/platform-events")
def platform_events():
    signature = request.headers.get("x-signature", "")
    if not is_valid_signature(request.get_data(), signature, os.environ["WEBHOOK_SIGNING_KEY"]):
        abort(401)
    event = request.get_json()
    # Skip event["id"] if you've seen it, queue the work, and answer right away.
    return "", 204

Event classes

Which events fire also depends on how you send: see the event catalog.

Limitations

• A webhook subscribes to one event, and its event can't be changed.
• A failed delivery isn't guaranteed to be retried. If your URL was unavailable, reconcile from the API.
• Payloads are documented for compliance events and SuppressedEmail.Added only.