Skip to content
PayloadPuffin.
Join the waitlist

Your product has customers of its own, say Initech and Globex, and each of them wants webhooks. A channel is a slug, such as initech, that addresses events inside an app. You typically use one per customer. You name channels on an event, and each destination lists the channels it receives.

Which destinations receive an event

The channels field on POST /v1/events is an optional list. Leaving it out and sending [] mean the same thing: the event names no channel. The destination's channels list decides the rest. Each row is a destination's channels, and each column is the channels an event names:

DestinationNo channelsglobexglobex, initech
[]delivereddelivereddelivered
["globex"]not delivereddelivereddelivered
["initech"]not deliverednot delivereddelivered

A destination with an empty channels list receives every event. A destination that lists channels receives only events that name at least one of them. An event that names no channel never reaches a destination that lists channels, so an untagged event can't leak to one of your customers. "channels": null is refused with 400.

The destination's eventTypes list must match too. An event that names globex doesn't reach Globex's destination when that destination doesn't list the event's type. An event produces at most one delivery per destination, however many of its channels the destination lists.

PayloadPuffin makes this decision once, when it creates the event's deliveries, usually moments after it accepts the event. The deliveries keep the result.

Give a destination channels

Set channels when you create the destination, or change it later with Update a destination. "channels": [] makes the destination receive events whatever channels they name, including events that name none.

JSON
{ "name": "Initech billing", "url": "https://hooks.initech.example/payloadpuffin", "channels": ["initech"] }

For your own internal destinations, leave channels empty to receive everything, or pick an ordinary slug such as internal and name it on the events that should reach them. The slug has no special meaning: "channels": ["initech", "internal"] reaches Initech's destinations, your internal ones and every destination with no channels.

Changing a destination's channels applies to every event whose deliveries are created afterwards, including one accepted just before the change. Deliveries created earlier keep going where they were going, and retries never move them. The destination's rate limit and circuit breaker belong to the destination, so a channel change doesn't reset them.

Channel slugs

A slug is 1 to 64 characters of lowercase letters and digits, in groups joined by single hyphens: initech, some-channel, acme2. An event can name up to 10 channels, and a destination can list up to 100.

A channel holds up to 10 destinations, and an app has up to 10 destinations that list no channel. Creating or changing a destination that would add an 11th is refused with 400. A destination already on a full channel keeps it.

PayloadPuffin checks slugs exactly as you send them. Initech, some_channel and -initech are refused with 400, so lowercase the slug yourself before you send it.

A well-formed slug that no destination lists is fine. The event is accepted and reaches only the destinations with no channels, the same as an event type that no destination lists.

Channels appear when you name them

There is no API to create a channel, and you don't need one. Listing a slug on a destination records the channel. An event that names a slug records nothing beyond the slug on the event itself, so a typo such as intiech shows up on that event and nowhere else.

There is no API to list channels either. You see them through the events that named them: List events and Get an event return channels on every event, as [] for an event that named no channel, or the sorted slugs.

A channel is not a security boundary

An API key belongs to an app, not to a channel. Any key that can send events to the app can address every channel in it, and any key that can read events or deliveries reads them for every channel. There is no channel-scoped credential.

Use channels to steer events between your customers' destinations. To keep data apart, use separate apps: staging and production, for example, each get their own app and their own keys.

Retries keep their original channels

Idempotency ignores channels. If you retry a request with the same Idempotency-Key but a different channel list, you get the first request's receipt, and the event keeps the first request's channels. Use a new key to address a different set of channels. See Idempotency.

Next steps

Destinations explains both filters and how to change them.