Anyone who has a source's URL can send to it. Most providers sign each webhook with a secret you share with them, so you can tell their requests from anyone else's. A source with signature verification refuses a request whose signature doesn't match with 401 and stores nothing. A source without one is URL only.
There are no presets: you copy the settings from the provider's webhook docs. The examples below cover GitHub, Stripe, Slack and Standard Webhooks.
Add verification
In the console, select the source and click Add verification in the Signature section. With the API, Set up signature verification for a source takes the same settings and needs sources:write:
algorithm: the HMAC hash,sha256,sha1orsha512.header: the header that carries the signature, such asx-hub-signature-256.encoding: how the signature is written,hexorbase64.prefix: what each signature starts with, such assha256=. It's removed before comparing.delimiter: what separates entries when the header holds several, such as,for Stripe. Empty means the header is one signature.timestamp: for a provider that signs a timestamp, itsheader, an optionalprefixwhen the timestamp is one entry of a header, andtoleranceSeconds, 300 unless you set it. A request whose timestamp is further than that from when it arrived fails.signedContent: what the provider signs.{body}is the raw body,{timestamp}the timestamp and{header:name}another header. It's{body}unless you set it.secretEncoding:textuses the secret's characters as the key, andbase64decodes it first, leaving out awhsec_start.secret: the signing secret. It's required the first time and never shown again.
curl -X PUT "https://api.payloadpuffin.com/v1/sources/$SOURCE_ID/signature" \
-H "Authorization: Bearer $PAYLOADPUFFIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"algorithm": "sha256", "header": "x-hub-signature-256", "encoding": "hex", "prefix": "sha256=", "secret": "'"$GITHUB_WEBHOOK_SECRET"'"}'A change can take up to a minute to apply everywhere. Verification runs on the body exactly as it arrived, before PayloadPuffin stores the request.
Provider examples
These are the settings each provider's docs describe. Leave out any setting not shown.
| Provider | Settings |
|---|---|
| GitHub | header x-hub-signature-256, encoding hex, prefix sha256= |
| Stripe | header stripe-signature, encoding hex, delimiter ,, prefix v1=, timestamp header stripe-signature with prefix t=, signedContent {timestamp}.{body} |
| Slack | header x-slack-signature, encoding hex, prefix v0=, timestamp header x-slack-request-timestamp, signedContent v0:{timestamp}:{body} |
| Standard Webhooks | header webhook-signature, encoding base64, delimiter a space, prefix v1,, secretEncoding base64, timestamp header webhook-timestamp, signedContent {header:webhook-id}.{timestamp}.{body} |
Every one of them uses sha256. Paste Stripe's whsec_ secret whole, as text.
Change the secret
A new secret keeps the current one working until a time you choose, from immediately up to in 7 days, so requests signed with either pass while both sides switch. Enter it in New signing secret and choose Stop the current secret, or send secret with expiry to the API. While the previous secret still works, a third one is refused with 409. The Signature section shows until when the previous secret works, and Stop the previous secret ends it now, as Expire the previous source signing secret does.
How to switch depends on the provider:
- When the provider signs with both secrets for a while, as Stripe and Standard Webhooks do, roll the secret at the provider, then paste the new one here. No request fails.
- When you choose the secret, as with GitHub, set the new secret here first, then change it at the provider.
- When the provider switches at once, the requests in between fail. Turn on store unverified requests for the change and rerun them afterwards.
Debug with store unverified requests
A wrong setting refuses every request, and a refused request isn't stored, so there's nothing to look at. While you set up verification, choose Store unverified under Requests that fail verification, or set storeUnverified to true.
A request that fails verification then gets 202 and becomes an unbuilt event whose reason names the step that failed: the header is missing, the timestamp is outside the tolerance, or the signature doesn't match. It isn't delivered. An unverified request also doesn't count toward duplicates, so a forged request can't block the provider's real retry.
Fix the settings, then rerun each event with Rerun an unbuilt event. The rerun checks the stored request against the settings as they are now, measuring the timestamp tolerance from when the request arrived, so a rerun hours later still passes. If it passes, the event is built and delivered; if not, the rerun answers 409 and the event keeps the new reason.
A rerun can't check a request whose signature header PayloadPuffin stored redacted: a header whose name contains token, secret, password or api-key is masked before storage.
Turn the setting off once verification works. While it's on, the source's panel shows a warning, and the source list marks the source with a warning icon.
Delete verification
Click Edit verification in the Signature section, then Delete verification, or Delete a source's signature verification, deletes the settings and both secrets. The source is URL only again, so rerunning an event it stored unverified builds and delivers it without verification. Deleting the source instead keeps those events unbuilt.