Your application sends events to PayloadPuffin, and PayloadPuffin delivers them to your destinations. Every event takes the same path, from its sender to each destination it matches.
Choose how events reach PayloadPuffin:
- Send events when your service calls the API.
- Receive webhooks when another service sends requests to a URL you create for it.
Here is one event that matches three destinations:
- The sender is your service, which calls
POST /v1/eventswith an API key, or another service's webhook to a source: a URL you create for it. - An event is what the sender sent and PayloadPuffin accepted.
- A delivery is that event, owed to one destination. Each one succeeds, retries or fails on its own.
- An attempt is one HTTP request made for a delivery. A retry is another attempt of the same delivery.
- A transform is optional code on a destination that rewrites the payload before each attempt.
- A destination is the receiver you configure: a URL, with filters that decide which events it is owed.
Who owns what
An organization is your account with PayloadPuffin. It owns your apps, and each app is one environment, such as staging or production. Everything you configure or send belongs to exactly one app, and an API key works for one app only, so staging traffic never reaches a production destination.
A channel is a slug such as initech that addresses events inside an app, typically one per customer. An event names the channels it is for, and a destination lists the channels it receives. A channel doesn't keep anything apart: an API key for the app can address every channel in it.
How an event finds its destinations
Every event has a type that you choose, such as customer.created. A destination has two filters: the event types it receives and the channels it receives. An empty filter matches everything, so a new destination receives every event you send, with or without channels. A destination that lists channels receives only events that name one of them.
Each matching destination gets one delivery. Zero matches means zero deliveries: the event is still accepted, and you can still look it up to see why nothing arrived.
Without a transform, the destination receives the payload bytes exactly as you sent them.
What a 202 means
A 202 receipt means PayloadPuffin has stored the event durably and will deliver it. It does not mean any destination has received it yet: delivery happens afterwards, and a newly accepted event may take a moment to appear in event queries.
Acceptance is not delivery success. If no destination matches the event, it is accepted and produces no deliveries. Each delivery is retried on its own, and your receiver may see the same event more than once, so make it safe to process duplicates.
Next steps
- Send your first event walks through sending an event and reading its receipt.
- Webhook didn't arrive helps you find what stopped it.
- Send an event is the reference for
POST /v1/events, and Get an event reports what happened to one. - Create a destination and List deliveries cover the other side of the pipeline.