Send a customer.created event that matches the filters of your billing service and your CRM sync, and PayloadPuffin creates two deliveries. A delivery is that event owed to one destination. Each has its own state, retries and outcome. The billing delivery can succeed while the CRM delivery is still retrying.
When something didn't arrive, the delivery is what you inspect, and it's what you resend. Each try within it is an attempt.
Where deliveries come from
PayloadPuffin creates deliveries once, when it processes an accepted event: one for each enabled destination whose filters match the event. The result is fixed at that moment. If you change a destination an hour later, the deliveries that already exist keep going where they were going.
An event that matches no destination gets no deliveries. It's still accepted, and the event list reports it as unmatched, so "it went nowhere" is something you can see rather than guess.
States
A delivery is always in one of six states:
status | Meaning |
|---|---|
pending | Owed, with no attempt made yet. |
delivering | An attempt is in progress right now. |
retrying | An attempt failed, and the next one is scheduled at nextAttemptAt. |
delivered | An attempt got a 2xx response. Final. |
failed | The last allowed attempt failed, or the failure can't be retried. Final. |
held | Owed, but deliberately not attempted. It waits for you to resend it. |
After delivered or failed, PayloadPuffin does nothing more on its own. Retries shows how a delivery moves between the states and when it stops.
held is for events that reached processing more than 48 hours after they were accepted. A burst of two-day-old webhooks can do more harm than good, so PayloadPuffin records the deliveries and leaves the decision to you. A held delivery isn't final: you can resend it until its event's retention ends.
Delivery is at least once
A delivered delivery means one attempt got a 2xx. It doesn't mean the destination saw the event only once. If a destination processes a request but its answer is lost or arrives after the timeout, PayloadPuffin records a failure and tries again. A resend sends again even after a success.
Every attempt of a delivery carries the delivery's ID in the webhook-id header, and the ID stays the same across retries and resends. Your receiver must handle duplicates: record the webhook-id values you've processed and skip a repeat.
Read deliveries
GET /v1/deliveries lists deliveries newest first and filters by status, eventId and destinationId. Two filters find work that is owed but not happening: ?status=held and ?status=failed.
GET /v1/deliveries/{deliveryId} returns one delivery with every attempt, oldest first. Listing and reading deliveries need an API key with the deliveries:read scope. Get an event lists the event's deliveries without their attempts.
A delivery names its destination with id, name and deleted. A deleted destination keeps the name it had, and deleted is true.
Next steps
- Attempts explains what one try records.
- Retries explains the schedule and when it stops.
- Resending a delivery sends a held or failed delivery again.