Inbound Webhooks

Your systems send events to Courier. Courier gives you a URL, and you point your webhooks at it. Each event that arrives is parsed and made available to the rest of the platform, most commonly as a Webhook trigger on a journey. Use one when a third-party system can send an HTTP request but can’t call the Courier API directly. For the opposite direction, where Courier notifies your systems about message and template activity, see Outbound Webhooks.

Register an Inbound Webhook

Go to Settings > Webhooks, under Developers, and find the Inbound Webhooks section.
Click Add, then give the webhook a name and description.
Save. Courier generates a unique URL and shows it in the URL column, 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, and its events are tied to that name, so pick something you’ll recognize later.

Send Events

Point the source system at the generated URL and POST your JSON. No API key or auth header is needed. The URL itself 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 to get 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 the event names and payload shape from events it has actually received, so event pickers and variable hints stay empty until at least one event 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 in the array as its own event
Anything else	Keeps the whole payload as a string on a `raw` field, and names the event `custom`

Courier answers 202 once it accepts the request. A 404 means the URL is wrong or no longer exists, in which case create a new webhook and repoint your system at the new URL.

Reserved Fields

Courier reads two fields out of a JSON payload if they’re present.

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

The userId has to match an existing Courier user. Without a recipient there’s nothing to send to, so the event won’t start a journey.

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

Use the Events

Point a journey’s Webhook trigger at the webhook by name. Optionally narrow it to a single event name, or leave it open to start on any event from that source. Payload fields become variables on the journey run.

Platform

Developer Tools

Help

Inbound Webhooks

Register an Inbound Webhook

Send Events

Payload Handling

Reserved Fields

Use the Events

​Register an Inbound Webhook

​Send Events

​Payload Handling

​Reserved Fields

​Use the Events

Register an Inbound Webhook

Send Events

Payload Handling

Reserved Fields

Use the Events