Outbound Webhooks

Courier sends events to your systems. Add your endpoint URL and Courier will POST to it when something happens in your workspace, such as a message being sent, delivered, opened, or failing, a template being published, or an audience changing. For the opposite direction, where your systems send events to Courier, see Inbound Webhooks.

Adding a New Webhook Destination

Go to Settings > Webhooks, under Developers, and find the Outbound Webhooks section.
Click Add.
Give the destination a name and enter its URL. The endpoint needs to accept a POST request.

Webhooks are scoped to the environment where they are created. A webhook created in the test environment will only fire for test events; it will not receive production events, and vice versa. If you need webhooks in both environments, create separate webhook destinations in each.

Handling Requests from Courier

Read the Event Data

Courier sends the event data in the request body. Each event is structured as an object with a type property and related resource data nested under the data property.

Handle the Event

Handle events based on the type property in the payload. Additional event types may be added in the future, so your handler should gracefully ignore unknown types.

Event type	Fired when
`message:updated`	A message changes status
`notification:submitted`	A template is submitted for review
`notification:submission_canceled`	A pending submission is canceled
`notification:published`	A template is published
`audiences:updated`	An audience is created or updated
`audiences:user:matched`	A user starts matching an audience filter
`audiences:user:unmatched`	A user stops matching an audience filter
`audiences:calculated`	Courier finishes recalculating an audience

Return a 2xx Response

Courier gives your endpoint 10 seconds to respond. Acknowledge the event first and do the real work afterwards, in a queue or background job, so a slow dependency doesn’t turn into a delivery failure.

Delivery and Retries

Courier retries a delivery when the failure looks temporary:

Outcome	Retried
Network error, or no response before the 10 second timeout	Yes
`408`, `429`, or any `5xx`	Yes
Other `4xx`	No

Retries continue for roughly a day before Courier gives up. An event can therefore arrive more than once, so make your handler idempotent. Note that data.id identifies the resource rather than the event, so a single message produces several events that share it.

Verifying Signatures

Set a secret on the webhook and Courier signs every event it sends to that destination, adding a courier-signature header. Verifying it confirms an event came from Courier and not a third party. Without a secret, no header is sent.

t=1631816343012,signature=33777cdae0468ff0939b3609d02d14e6e80ca093c2ea233455f0767055218875

t is the time Courier signed the event, in milliseconds since the epoch. signature is an HMAC-SHA256 digest, hex encoded. Get the secret from Webhooks settings by opening the webhook configuration. You need it as the HMAC key.

Step 1: Extract the Timestamp and Signature from the Header

Split the header on , to get a list of elements, then split each element on = to get a prefix and value pair. The value for the prefix t is the timestamp, and signature is the signature.

Step 2: Prepare the `signed_payload` String

Concatenate the timestamp, a . separator, and the raw request body.

Use the raw body exactly as it arrived, not a parsed object you re-serialize. JSON.stringify on a parsed payload can reorder keys or change whitespace, which produces a different hash and a signature that never matches. Most frameworks need to be configured to keep the raw body, for example express.raw() or Next.js with the body parser disabled.

Step 3: Determine the Expected Signature

Compute an HMAC with the SHA256 hash function, using the webhook secret as the key and the signed_payload string as the message.

Step 4: Compare the Signatures

Compare your computed signature to the one in the header with a constant-time comparison, so a mismatch doesn’t leak information through timing. Check the timestamp separately. Reject events whose timestamp falls outside a tolerance window you choose, which limits how long a captured request stays replayable.

import crypto from "crypto";

function isValidCourierSignature(
  header: string,
  rawBody: string,
  secret: string,
  toleranceMs = 5 * 60 * 1000
): boolean {
  const parts = Object.fromEntries(
    header.split(",").map((pair) => pair.split("="))
  );
  const { t: timestamp, signature } = parts;

  if (!timestamp || !signature) return false;

  // Reject stale events to limit replay.
  if (Math.abs(Date.now() - Number(timestamp)) > toleranceMs) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`, "utf8")
    .digest("hex");

  const expectedBuffer = Buffer.from(expected, "hex");
  const receivedBuffer = Buffer.from(signature, "hex");

  return (
    expectedBuffer.length === receivedBuffer.length &&
    crypto.timingSafeEqual(expectedBuffer, receivedBuffer)
  );
}

// rawBody is the unparsed request body, not JSON.stringify(req.body)
const isValid = isValidCourierSignature(
  req.headers["courier-signature"],
  rawBody,
  process.env.COURIER_WEBHOOK_SECRET
);

Event Data

message:updated

Each message status change triggers a message:updated webhook event. Delivery statuses like DELIVERED depend on your email provider asynchronously confirming delivery, while engagement statuses like OPENED and CLICKED are tracked by Courier directly and fire as soon as the recipient acts. This means you may receive engagement events before delivery confirmation, or without it arriving at all. For the full status lifecycle diagram and definitions, see Message Statuses. The data property in the webhook response payload for the message:updated event is identical to the information returned from the GET /message/:message_id endpoint. Any metadata associated with the message is included in the data property. This includes:

trace_id
tags
event
utm

Timestamp fields accumulate as the message progresses, so a CLICKED event still carries enqueued, sent, delivered, and opened. Here’s a DELIVERED event:

{
  "data": {
    "enqueued": 1630512466717,
    "sent": 1630512468691,
    "delivered": 1630512501708,
    "event": "SFTYJKSF0241SVH2TWY97TTFFTQG",
    "id": "1-612fa552-15f7d6ba51bf229857c037a7",
    "notification": "SFTYJKSF0241SVH2TWY97TTFFTQG",
    "providers": [
      {
        "provider": "slack",
        "status": "DELIVERED",
        "channel": {
          "key": "direct_message:slack",
          "name": "Slack",
          "template": "SFTYJKSF0241SVH2TWY97TTFFTQG"
        },
        "reference": {
          "channel": "C04EXAMPLE",
          "ts": "1630512468.000700"
        },
        "sent": 1630512468691,
        "delivered": 1630512501708
      }
    ],
    "recipient": "b19fb0e0-8cd6-4337-b41c-92c780c80d1a",
    "recipientId": "b19fb0e0-8cd6-4337-b41c-92c780c80d1a",
    "status": "DELIVERED"
  },
  "type": "message:updated"
}

What each status adds to data:

Status	Added fields
`ENQUEUED`	`enqueued`
`SENT`	`sent`, and `sent` on the matching entry in `providers`
`DELIVERED`	`delivered`, and `delivered` on the matching entry in `providers`
`OPENED`	`opened`
`CLICKED`	`clicked`
`UNROUTABLE`	`reason` (for example `NO_PROVIDERS`) and `error` with the message. `providers` is empty.
`UNDELIVERABLE`	`reason` (for example `UNSUBSCRIBED`) and `error`, plus `error` on the failing entry in `providers`

Notification Template Events

Courier emits three events for the template submission workflow. Use them to integrate with a translation management system (TMS) or a custom approval workflow.

notification:submitted

Fired when a template is submitted for review, meaning it entered an approval workflow and has not been published yet.

{
  "data": {
    "id": "<NOTIFICATION_ID>",
    "submission_id": 1620095270807 // submission ID is a timestamp of submission
  },
  "type": "notification:submitted"
}

notification:submission_canceled

Fired when a pending submission is canceled before it is published.

{
  "data": {
    "id": "<NOTIFICATION_ID>",
    "canceled_at": 1620095280807,
    "submission_id": 1620095270807
  },
  "type": "notification:submission_canceled"
}

notification:published

Fired when a template is published directly with no approval workflow, or when a submission is approved and auto-published. This is the event to listen for if you want to sync template content to an external system.

{
  "data": {
    "id": "<NOTIFICATION_ID>",
    "published_at": 1620095270807
  },
  "type": "notification:published"
}

audiences:updated

Fired when an audience is created or updated.

{
  "data": {
    "audience_id": "software-engineers",
    "audience_version": 11,
    "filter": {
      "path": "title",
      "value": "Software Engineer",
      "operator": "EQ"
    }
  },
  "type": "audiences:updated"
}

audiences:user:matched

Fired when a user starts matching an audience, which usually happens when the user is created or updated. If a user’s profile matches the audience’s filters, the user is matched to the audience. This is the same event behind the journey Audience trigger, so you can react to it either with a webhook or by starting a journey.

{
  "data": {
    "audience_id": "software-engineers",
    "audience_version": 11,
    "reason": "EQ('title', 'Software Engineer') => true",
    "user_id": "user_123"
  },
  "type": "audiences:user:matched"
}

audiences:user:unmatched

Fired when a user stops matching an audience, which usually happens when the user is removed or updated so that they no longer match the audience’s filters.

{
  "data": {
    "audience_id": "software-engineers",
    "audience_version": 12,
    "reason": "EQ('title', 'Software Engineer') => false",
    "user_id": "user_123"
  },
  "type": "audiences:user:unmatched"
}

audiences:calculated

Fired when Courier finishes recalculating an audience. This background process runs every time you create or update an audience, and how long it takes depends on how many users are in your workspace.

{
  "data": {
    "audience_id": "software-engineers",
    "user_count": 1,
    "total_users": 28,
    "total_users_filtered": 27
  },
  "type": "audiences:calculated"
}

Platform

Developer Tools

Help

Outbound Webhooks

Adding a New Webhook Destination

Handling Requests from Courier

Read the Event Data

Handle the Event

Return a 2xx Response

Delivery and Retries

Verifying Signatures

Step 1: Extract the Timestamp and Signature from the Header

Step 2: Prepare the `signed_payload` String

Step 3: Determine the Expected Signature

Step 4: Compare the Signatures

Event Data

message:updated

Notification Template Events

notification:submitted

notification:submission_canceled

notification:published

audiences:updated

audiences:user:matched

audiences:user:unmatched

audiences:calculated

​Adding a New Webhook Destination

​Handling Requests from Courier

​Read the Event Data

​Handle the Event

​Return a 2xx Response

​Delivery and Retries

​Verifying Signatures

​Step 1: Extract the Timestamp and Signature from the Header

​Step 2: Prepare the signed_payload String

​Step 3: Determine the Expected Signature

​Step 4: Compare the Signatures

​Event Data

​message:updated

​Notification Template Events

​notification:submitted

​notification:submission_canceled

​notification:published

​audiences:updated

​audiences:user:matched

​audiences:user:unmatched

​audiences:calculated

Adding a New Webhook Destination

Handling Requests from Courier

Read the Event Data

Handle the Event

Return a 2xx Response

Delivery and Retries

Verifying Signatures

Step 1: Extract the Timestamp and Signature from the Header

Step 2: Prepare the `signed_payload` String

Step 3: Determine the Expected Signature

Step 4: Compare the Signatures

Event Data

message:updated

Notification Template Events

notification:submitted

notification:submission_canceled

notification:published

audiences:updated

audiences:user:matched

audiences:user:unmatched

audiences:calculated