Skip to content
PayloadPuffin.
Join the waitlist

Receive webhooks

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 type of every event the source receives, such as billing.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:

Shell
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:

TEXT
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 as application/vnd.api+json
  • forms: application/x-www-form-urlencoded and multipart/form-data
  • UTF-8 text: text/plain, text/xml, application/xml, or an XML type such as application/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:

Deleting a source stops its URL within a minute. Its events stay until retention removes them.