Inbound webhooks

Courier gives you a URL. You point an external system’s webhooks at it. Courier parses each arriving event and makes it available to the platform, most often as a on a journey. Use one when a third-party system can send an HTTP request but cannot call the Courier API directly.

How it works

Register a webhook

In , under Developers, find the Inbound Webhooks section.
Select Add, then give the webhook a name and description.
Save. Courier generates a unique URL in the form https://api.courier.com/inbound/webhook/<token>.

The name is permanent. You select the webhook by name wherever you consume its events, so make it recognizable.

Send events

Point the source system at that URL and POST your JSON. No API key or auth header is needed. The URL carries a signed token that identifies your workspace.

Treat the webhook URL as a secret. Anyone who has it can send events into your workspace. If it leaks, delete the webhook and create a new one for a fresh URL.

curl -X POST https://api.courier.com/inbound/webhook/YOUR_WEBHOOK_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "event": "order-shipped",
    "userId": "user_123",
    "properties": {
      "order_id": "ORD-9042",
      "carrier": "UPS"
    }
  }'

Send real traffic before you build against the webhook. Courier learns event names and payload shape from events it has received. Event pickers and variable hints stay empty until the first one arrives.

Payload handling

Courier accepts any payload up to 6 MB.

Payload	What Courier does
JSON object	Parses it and exposes the fields as data
JSON array	Unpacks it and treats each object as its own event
Anything else	Keeps the payload as a string on a `raw` field, and names the event `custom`

Courier answers 202 when it accepts the request. A 404 means the URL is wrong or no longer exists.

Reserved fields

Courier reads two fields from a JSON payload, if present.

Field	Purpose
`event`	The event name, used to pick which events start a workflow. Must be a string. Without it, Courier names the event `custom`.
`userId`	Identifies the recipient. Courier resolves the from it and loads their profile data. A string or number, coerced to a string.

Every other field is yours. Courier passes them through as data to whatever consumes the event.

Limits & behavior

userId must match an existing Courier user. With no recipient to send to, the event will not start a journey.
The URL is the credential. There is no separate auth header, so anyone holding the URL can post events.
Payloads cap at 6 MB. Larger requests are rejected.

FAQ

Why is my event picker empty?

Courier learns event names from traffic it has received. Post one real event and the name appears.

What if the webhook URL leaks?

Delete the webhook and create a new one. That issues a fresh URL, and the old one stops accepting events.

Can I send a batch of events at once?

Post a JSON array. Courier treats each object in it as its own event.

Get started

Send messages

Journeys

Broadcasts

Design

Recipients

Tenants

Monitoring

Workspaces

Resources

Inbound webhooks

How it works

Register a webhook

Send events

Payload handling

Reserved fields

Limits & behavior

FAQ

​How it works

​Register a webhook

​Send events

​Payload handling

​Reserved fields

​Limits & behavior

​FAQ

How it works

Register a webhook

Send events

Payload handling

Reserved fields

Limits & behavior

FAQ