Skip to main content
An outbound webhook sends Courier’s events to an endpoint you own, as a signed POST. Use it when your own system needs to react to a message’s status, such as updating an order record when a receipt is delivered.

​
Add a destination

1

Open the webhook settings

Go to and find Outbound Webhooks.
2

Add the endpoint

Select Add, give the destination a name, and enter its URL. The endpoint has to accept a POST.
3

Save the signing secret

Courier creates a whsec_... secret for the destination. Store it where your handler can read it, so you can .
Destinations belong to one environment. A destination added in Test receives only Test events. Add one in each environment you need.

​
Handle events

Every event arrives as { "type": "...", "data": {...} }:
  1. Verify the signature before you trust the body. See .
  2. Branch on type. Every destination receives every event type, so ignore the ones you don’t need, and ignore types you don’t recognize, since Courier may add new ones. lists them all.
  3. Return a 2xx within 10 seconds. Acknowledge first and do the real work in a queue or background job, so a slow dependency doesn’t turn into a failed delivery.
  4. Make your handler idempotent. A retry can deliver the same event twice, and one message produces several message:updated events that share its data.id.

​
Retries

Courier retries a delivery when the failure looks temporary: Retries start a few seconds apart, grow to 15-minute intervals, and continue for about a day. After that the event is dropped. A destination is never turned off automatically, so a broken endpoint keeps getting retries until each event ages out. To recover events you missed during an outage, read the messages from the and preference changes from the .

​
Limits & behavior

  • Setup is in the dashboard. There’s no API for creating destinations.
  • No timestamp in the body. The send time is on the courier-signature header.

​
FAQ

Every destination receives every event type. Filter on the type field in your handler.
Courier retries with an increasing backoff for about a day, then drops the event. Events that aged out during the outage are gone, so backfill from the Messages API if you need them.
Use webhooks when your own code needs to act on each event. Use to see Courier’s metrics and logs in Datadog, New Relic, or another OpenTelemetry tool.
Outbound webhooks send Courier’s events to you. let another system send events into Courier, usually to start a journey.