Your billing service and a customer's receiver both need the same events. Configure a destination for each: a receiver's URL, two filters, a signing secret and delivery settings. Two destinations may share a URL.
Create a destination
Create a destination takes a name (1 to 120 characters) and a url, and needs an API key with the destinations:write scope. It answers 201 with the destination and its signing secret. That's the only response that carries the secret without you asking for it, so store it where your receiver can read it.
Each app can have as many destinations as your organization's plan allows. One more is refused with 400; delete a destination to free a slot.
Two optional lists decide which events the destination receives:
eventTypeslists the event types it receives, such as["invoice.paid"]. Each entry follows the same rules as an event'stype.channelslists the customers it serves, by slug, such as["globex"]. See Channels.
Leave a list out, or send [], and that list matches everything. A non-empty list matches an event that shares at least one entry with it, and both lists must match. An event that names no channel reaches only destinations with an empty channels list. Each list holds at most 100 entries.
{
"name": "Globex billing",
"url": "https://hooks.globex.example/payloadpuffin",
"eventTypes": ["invoice.paid", "invoice.failed"],
"channels": ["globex"]
}The filters are saved in the same step as the destination, so it's never a catch-all, not even for a moment. From then on, every matching event produces one delivery to it. Events whose deliveries were created before the destination existed aren't sent to it.
A new destination sends each payload as you sent it. To change the payload or its format, such as a form instead of JSON, link a transform with transformId. Several destinations can link the same transform.
What PayloadPuffin sends
Each attempt is an HTTP POST to the destination's URL, with the payload as the body and content-type: application/json. A transform can send another body and content-type. Three headers identify and sign the request: webhook-id, webhook-timestamp and webhook-signature. Check them on every request; see Verify signatures.
The destination has 5 seconds to answer each attempt. Any 2xx status delivers the delivery. Other responses, timeouts and network errors fail the attempt. See Retries for which failures are retried.
The destination's URL must use HTTPS. The signature proves who sent the request; HTTPS keeps the payload private on the way.
Change a destination
Update a destination changes the name, the url, the eventTypes, the channels or enabled. A list you send replaces the stored list. The signing secret, the delivery policy and the history stay as they were.
A filter change applies to every event whose deliveries are created afterwards. Deliveries that already exist keep going where they were going.
PayloadPuffin reads the URL when it prepares each attempt. A delivery that is still waiting, including one between retries, goes to the new URL on its next attempt. Each attempt's record keeps the URL it was actually sent to.
Other settings have their own operations:
- Delivery controls set how fast and how many requests at once the destination receives.
- Recording chooses whether each attempt's request and response are kept.
- Verify signatures covers rotating the signing secret.
Turn a destination off
Send "enabled": false with Update a destination, or use the toggle on the destination in the console. New events stop producing deliveries to it, and it keeps its filters for when you turn it back on. Deliveries that already exist are still sent.
Turning it off is the only way to make a destination receive nothing. An empty list always means "everything".
Delete a destination
Delete a destination removes the destination and answers 200 with its ID. New events no longer produce deliveries to it.
Deliveries that already exist aren't deleted. A delivery that was still waiting to be sent settles as failed without another attempt, so its history shows what happened instead of skipping it silently. The destination's past deliveries and attempts stay readable until their events expire.
Is it healthy?
Every destination read carries a health label that answers "should I look at this?":
health | Meaning |
|---|---|
suspended | Its circuit is open or probing, or it is paused automatically |
unused | No delivery was ever created for it |
failing | An attempt failed since the last success, or under half succeeded in 24 hours |
idle | It has deliveries, but none were attempted in the last 24 hours |
healthy | None of the above |
The first row that applies wins. idle describes traffic, not a problem. Delivery controls explains the circuit and the automatic pause. Get a destination adds latency percentiles, the last failure, and the five newest deliveries.