A customer signed up, an invoice was paid, an export finished. Your application tells PayloadPuffin what happened by sending an event. You send it once with POST /v1/events, and PayloadPuffin works out which destinations should hear about it.
{
"type": "customer.created",
"channels": ["initech"],
"payload": { "id": "cus_1042", "email": "ada@example.com" }
}You choose the type. It's a name in your own vocabulary, and destination filters match it exactly. A type is 1 to 64 characters. Spaces, commas and other printable characters are fine, but control characters such as a newline or tab are refused with 400. The pp/ prefix is reserved for PayloadPuffin; your types can't start with it.
The payload is any JSON value. Destinations receive its bytes exactly as you sent them, unless a transform rewrites them.
channels is optional and names the channels the event is for, usually the customer it belongs to. Leaving it out and sending [] mean the same.
A webhook from another service can become an event too, through a source: a URL that turns each request it accepts into an event of the source's type and channels.
Accepted is not delivered
Sending an event and delivering it are two separate jobs, and the API keeps them apart. POST /v1/events answers as soon as the event is stored. Delivery to your destinations happens afterwards, on its own schedule.
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.
The whole request may be at most 262,144 bytes (256 KiB), JSON wrapper included, on every plan. Everything outside payload may be at most 65,536 bytes. A request over either limit is refused with 413 before anything is stored.
One event, many deliveries
When PayloadPuffin processes an accepted event, it matches the event against the filters of every enabled destination in the app. Each matching destination gets one delivery: this event, owed to that destination. An event that matches three destinations has three deliveries, and each one succeeds, retries or fails on its own.
An event that matches no destination has no deliveries. It's still accepted, listed and readable, so you can find it when you wonder why nothing arrived.
The event never changes after it's accepted. Everything that happens later, such as retries, failures and resends, is recorded on its deliveries and their attempts.
Status sums up the deliveries
An event has no delivery state of its own. The status you see in the event list sums up its deliveries, worst state first:
status | When |
|---|---|
unbuilt | A source stored the request but couldn't build the event, so it has no deliveries. |
failed | At least one delivery failed, even if others were delivered. |
retrying | Nothing failed, and at least one delivery is waiting for its next attempt. |
pending | Nothing failed or is retrying, and a delivery is owed, held, or in flight. |
delivered | Every delivery was delivered. |
unmatched | The event matched no destination, so it has no deliveries. |
An unbuilt event comes from a source, and unbuiltReason says why it couldn't be built. Fix the source's transform and rerun it: see Unbuilt events. It's never failed or unmatched.
So failed doesn't mean the event was rejected. A rejected event has no status at all, because it was never accepted. failed means PayloadPuffin accepted the event and at least one destination never returned a 2xx.
Each list row also counts its deliveries by state in deliveries. When something failed, deliveries.failure names the destination, attempt number, status code and time of the failure to open first.
Read events
GET /v1/events lists events newest first, one row per event however many destinations it went to. It filters by:
status, using the summary above.?status=failedfinds every event with a failed delivery, and?status=unbuiltevery event a source couldn't build.destinationId, which matches events with at least one delivery to that destination.
Each event carries channels: [] for an event that named no channel, or the slugs it named, including when it matched no destination. There is no filter by channel.
Each event also carries sender, the ID of whoever sent it: the source it came through (src_...), the API key that sent it with POST /v1/events (apk_...), or the console user who sent a test event.
GET /v1/events/{eventId} returns one event with every delivery it produced: each one's destination, status and attempt count. One request answers "what happened to this event" for the whole fan-out, and Get a delivery returns one delivery's attempts. Both operations need an API key with the events:read scope.
Neither operation returns the payload. The event reports payloadSize and contentType, and the console shows the stored request itself. If you read an event immediately after its 202 receipt, it can answer 404 while PayloadPuffin processes it. If it stays missing, check the event ID and the API key's app. An event also answers 404 after its retention ends.
Next steps
- Idempotency makes a retried send safe.
- Retention explains how long an event and everything it produced are kept.
- Deliveries follows one event to one destination.