Payment providers, code hosts and most other services report what happened by sending webhooks. They don't hold a PayloadPuffin API key, so they can't call POST /v1/events. A source gives such a service a URL of its own instead. Every request the source accepts becomes an event, and PayloadPuffin delivers it to your destinations like any other.
Create a source
In the console, open Sources and click Create source. Give it:
- a Name, such as the service that sends to it,
- an Event type, the
typeof every event the source receives, such asbilling.webhook, - optional Channels, the channels every event from it names.
The dialog that follows shows the source's URL once. Copy it and give it to the sending service. With the API, Create a source returns the URL as secretUrl:
curl -X POST "https://api.payloadpuffin.com/v1/sources" \
-H "Authorization: Bearer $PAYLOADPUFFIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Billing provider", "defaultType": "billing.webhook", "defaultChannels": ["acme"]}'The key needs the sources:write scope. A new URL can take up to a minute to work everywhere.
The URL
A source's URL looks like this:
https://api.payloadpuffin.com/v1/inbound/src_01m4pa5v4wetwab7xhgrev2tag/pps_...The last part is a token, and the token is the only credential: whoever has the URL can send to it. PayloadPuffin stores only a hash of the token and shows the URL whole only when you create the source or rotate its URL. Every other read shows it without the token, and with the token's last four characters. If the URL leaks, rotate it.
A wrong token, a source that doesn't exist and a deleted source all get the same 404, so a caller can't learn which sources exist.
The token is all a URL-only source checks. To accept only the requests a provider signed, check their signatures. A provider that checks the URL before sending to it gets its answer from the source's URL checks.
What a request becomes
A source accepts a POST in these formats:
- JSON:
application/json, or a JSON type such asapplication/vnd.api+json - forms:
application/x-www-form-urlencodedandmultipart/form-data - UTF-8 text:
text/plain,text/xml,application/xml, or an XML type such asapplication/atom+xml
PayloadPuffin stores the request, answers 202 with the event's ID, and builds and delivers the event afterwards. Any other content type, and text that isn't valid UTF-8, gets 415, and nothing is stored.
Without a source transform, a JSON body becomes the event's payload, byte for byte, never parsed or reformatted, and the event's type and channels are the source's. A body in another format needs a source transform to become an event; without one it becomes an unbuilt event. The event's sender is the source's ID, so Get an event and the event list show where an event came from. Event detail in the console names the source.
The source's event type and channels are captured when a request arrives. Transform code is selected when PayloadPuffin builds the event. Publishing a transform can therefore change how already accepted requests are built. See Source transforms.
With signature verification, a request whose signature doesn't match gets 401 first, and nothing is stored.
A request gets the same limits as POST /v1/events: 402 when your organization refuses events after using its included billable units, 413 for a body over 262,144 bytes (256 KiB), and 429 for the ingest rate, the ingest volume and a size-violation cooldown, counted per source. Errors lists them.
A provider webhook over 256 KiB is refused, not cut short. Some providers send larger ones, such as a GitHub push event with many commits; that provider gets the 413 and retries or gives up by its own rules.
Unbuilt events
When a source can't build an event from a request it stored, the event is unbuilt: its transform threw, returned something that isn't an event, or ran too long, the body isn't JSON and the source has no transform, or the request failed the signature check while the source stores unverified requests. An unbuilt event has no deliveries and isn't counted toward your plan until it's built. Its status is unbuilt, and unbuiltReason says what went wrong.
To find them, filter the event list on ?status=unbuilt, or pick Unbuilt in the console's outcome filter. Event detail shows the reason, a link to the source's transform, and Rerun.
Fix the transform and publish it, then rerun the event with Rerun an unbuilt event, which needs the events:write scope. A rerun builds the event again from the stored request with the transform published at that moment, then delivers it. The event stays unbuilt until the build finishes, and a build that fails again replaces the reason. You can rerun an unbuilt event for as long as retention keeps it.
Duplicates
Services retry a webhook that didn't get a quick answer, sometimes for days. A request with an Idempotency-Key header, or else a webhook-id header, counts once per source for 24 hours: a repeat gets 202 with the first event's ID and creates nothing. Idempotency has the details.
Manage sources
The source's panel in the console edits its name, event type and channels, its signature check and URL checks, rotates its URL and deletes it. With the API, a key with sources:read lists and reads sources, and sources:write changes them:
- List sources and Get a source
- Update a source
- Set the GET URL check of a source, Remove the GET URL check of a source, Set the POST URL check of a source and Remove the POST URL check of a source
- Rotate a source token and Expire the previous source token
- Set up signature verification for a source, Delete a source's signature verification and Expire the previous source signing secret
- Delete a source
Deleting a source stops its URL within a minute. Its events stay until retention removes them.