Webhook event types

Every event arrives as { "type": "...", "data": {...} }. Branch on type, and ignore types you don’t recognize, since Courier may add new ones.

Event type	Fires 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:created`	An audience is created
`audiences:updated`	An audience’s definition changes
`audiences:deleted`	An audience is deleted
`audiences:calculated`	Courier finishes recalculating an audience
`audiences:user:matched`	A user starts matching an audience
`audiences:user:unmatched`	A user stops matching an audience
`preferences:user:updated`	A user changes a subscription preference

Message events

message:updated

Fires every time a message changes status. data is the same object the endpoint returns, including any metadata you sent (trace_id, tags, event, utm). Timestamps accumulate as the message moves along, so a CLICKED event still carries enqueued, sent, delivered, and opened. A DELIVERED event:

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

What each status adds to data:

Status	Adds
`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`, such as `NO_PROVIDERS`, and `error`. `providers` is empty.
`UNDELIVERABLE`	`reason`, such as `UNSUBSCRIBED`, and `error`, plus `error` on the failing entry in `providers`

DELIVERED comes from your provider and OPENED and CLICKED come from Courier’s tracking, so engagement events can arrive before the delivery event, or without it. See .

Template events

Use these to connect a translation management system or a custom approval workflow.

notification:submitted

Fires when a template is submitted for review and hasn’t been published yet. submission_id is the submission’s timestamp.

{
  "type": "notification:submitted",
  "data": {
    "id": "nt_01kx4h2jdafq8bk9aftxak4b40",
    "submission_id": 1620095270807
  }
}

notification:submission_canceled

Fires when a pending submission is canceled before it’s published.

{
  "type": "notification:submission_canceled",
  "data": {
    "id": "nt_01kx4h2jdafq8bk9aftxak4b40",
    "canceled_at": 1620095280807,
    "submission_id": 1620095270807
  }
}

notification:published

Fires when a template is published, either directly or when an approved submission publishes. Listen for this one to sync template content to another system.

{
  "type": "notification:published",
  "data": {
    "id": "nt_01kx4h2jdafq8bk9aftxak4b40",
    "published_at": 1620095270807
  }
}

Audience events

audiences:created, audiences:updated, and audiences:deleted fire when an audience is created, changed, or deleted. An audiences:updated event:

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

audiences:calculated

Fires when Courier finishes recalculating an audience’s membership. This runs every time an audience is created or updated, and takes longer the more users your workspace has.

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

audiences:user:matched

Fires when a user starts matching an audience’s filter, usually because their profile was created or updated. It’s the same event behind the journey audience trigger, so you can react to it with a webhook or by starting a journey.

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

audiences:user:unmatched

Fires when a user stops matching an audience’s filter, because their profile changed or was deleted.

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

Preference events

preferences:user:updated

Fires when a user changes their subscription preference for a topic, whether they change it on the hosted preferences page, unsubscribe link, or through the API. One event covers every kind of change: opting in, opting out, and editing which channels a topic uses. data describes a single change to a single topic.

{
  "type": "preferences:user:updated",
  "data": {
    "id": "eb4023e3-62cc-4488-a4fc-d98230994f6a",
    "timestamp": "2026-09-24T18:12:04.442Z",
    "user_id": "user_123",
    "tenant_id": "acme-corp",
    "topic_id": "pt_01kx4h2jdafq8bk996nn92357r",
    "topic_name": "Product updates",
    "status": "OPTED_OUT",
    "custom_routing": [],
    "has_custom_routing": false,
    "previous": {
      "status": "OPTED_IN",
      "custom_routing": ["email"],
      "has_custom_routing": true
    }
  }
}

custom_routing lists the channels a user picked for the topic and is empty unless has_custom_routing is true. tenant_id is absent when the change wasn’t made in a tenant. previous is absent when the earlier state isn’t known, such as the first time a user changes their preference for a topic.

Limits & behavior

One message produces several events. message:updated fires on every status change, so key your handler on data.id and data.status.
data.id identifies the resource, not the event. Retries and status changes can share it.
No timestamp in the body. The send time is on the courier-signature header.

FAQ

How many events does one message produce?

One per status change. A delivered and opened email produces at least four message:updated events: enqueued, sent, delivered, and opened.

Can I get the metadata I sent with the message?

data on message:updated carries the metadata from your send, including trace_id, tags, event, and utm.

Get started

Send messages

Journeys

Broadcasts

Design

In-app

Recipients

Tenants

Monitoring

Workspaces

Resources

Webhook event types

Message events

message:updated

Template events

notification:submitted

notification:submission_canceled

notification:published

Audience events

audiences:calculated

audiences:user:matched

audiences:user:unmatched

Preference events

preferences:user:updated

Limits & behavior

FAQ

​Message events

​message:updated

​Template events

​notification:submitted

​notification:submission_canceled

​notification:published

​Audience events

​audiences:calculated

​audiences:user:matched

​audiences:user:unmatched

​Preference events

​preferences:user:updated

​Limits & behavior

​FAQ

Message events

message:updated

Template events

notification:submitted

notification:submission_canceled

notification:published

Audience events

audiences:calculated

audiences:user:matched

audiences:user:unmatched

Preference events

preferences:user:updated

Limits & behavior

FAQ