Set up signature verification for a source
PUT/v1/sources/{sourceId}/signaturepreview
Require every request to a source to carry a valid HMAC signature over its raw body. A request that fails is refused with 401, or stored as an unbuilt event while storeUnverified is on. A new secret keeps the replaced one verifying until the chosen expiry, and is refused with 409 while an earlier replaced secret still verifies.
Path parameters
sourceIdstring RequiredA source ID, starting with src_.
Body
algorithmstring RequiredThe HMAC hash.
Allowed values: "sha256", "sha1", "sha512"
headerstring RequiredThe header that carries the signature, such as x-hub-signature-256.
1 to 100 characters
encodingstring RequiredHow the signature is written: hex or base64.
Allowed values: "hex", "base64"
secretEncodingstring OptionalHow the secret is used as the HMAC key: text uses its characters, base64 decodes it first (whsec_ is dropped). Default text.
Allowed values: "text", "base64"
delimiterstring OptionalWhat separates several entries in the signature header, such as “,” for Stripe or “ “ for Standard Webhooks. Empty: the header is one signature. Default empty.
At most 4 characters
prefixstring OptionalWhat each signature starts with, such as sha256= or v1,. It is removed before comparing. Default empty.
At most 32 characters
timestampobject | null OptionalA signed timestamp that limits replays. Null: none.
signedContentstring OptionalWhat the provider signs: {body} is the raw body, {timestamp} the timestamp and {header:name} another header. Default {body}.
6 to 256 characters
storeUnverifiedboolean OptionalStore a request that fails the check as an unbuilt event instead of refusing it with 401, to debug these settings. It is never delivered unless a rerun verifies it. Default false.
secretstring OptionalThe signing secret, as the provider shows it. Required the first time; omit it to keep the stored one. It is never returned.
1 to 512 characters
expirystring OptionalWhen a new secret replaces a stored one: how long the replaced secret keeps verifying, immediately or 1h up to 7d.
Allowed values: "immediately", "1h", "2h", "4h", "8h", "12h", "24h", "3d", "7d"
Returns
The command completed.200
dataobject RequiredA source: a URL a webhook provider sends requests to, each of which becomes an event.
idstring RequiredA source ID, starting with src_.
namestring RequiredHuman-readable label for the source, such as the provider that sends to it.
1 to 120 characters
urlstring RequiredThe source’s URL without its token. Requests go to this URL followed by / and the token, which is shown only when the source is created or its token rotated.
tokenLast4string RequiredThe last four characters of the token.
previousTokenExpiresAtstring | null RequiredWhen the token a rotation replaced stops working. Null when there is none.
defaultTypestring RequiredThe type of every event this source receives, for example billing.webhook.
1 to 64 characters
defaultChannelsstring[] RequiredChannels every event this source receives is addressed to. Empty: the events reach only destinations that list no channel. Stored sorted, without duplicates.
At most 10 items
signatureobject | null RequiredThe HMAC check every request must pass. Null: the source is URL only.
queryChallengeobject | null RequiredThe GET URL check. Null: none.
bodyChallengeobject | null RequiredThe POST URL check. Null: none.
transformIdstring | null RequiredThe transform that builds every event. Null: a JSON body becomes the payload as received.
createdAtstring (date-time) RequiredISO 8601 timestamp.
updatedAtstring (date-time) RequiredISO 8601 timestamp.
lastEventAtstring | null RequiredWhen this source last received a request that became an event, to the minute. Null when there is none.
Example
curl -X PUT "https://api.payloadpuffin.com/v1/sources/$SOURCEID/signature" \
-H "Authorization: Bearer $PAYLOADPUFFIN_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"algorithm":"sha256","header":"example","encoding":"hex"}'{
"data": {
"id": "id",
"name": "name",
"url": "url",
"tokenLast4": "tokenLast4",
"previousTokenExpiresAt": "previousTokenExpiresAt",
"defaultType": "defaultType",
"defaultChannels": [
"defaultChannels"
],
"signature": {
"algorithm": "sha256",
"header": "header",
"encoding": "hex",
"secretEncoding": "text",
"delimiter": "delimiter",
"prefix": "prefix",
"timestamp": {
"header": "header",
"prefix": "prefix",
"toleranceSeconds": 1
},
"signedContent": "signedContent",
"storeUnverified": true,
"previousSecretExpiresAt": "previousSecretExpiresAt"
},
"queryChallenge": {
"tokenParameter": "tokenParameter",
"token": "token",
"challengeParameter": "challengeParameter"
},
"bodyChallenge": {
"member": "member",
"value": "value",
"echo": "echo"
},
"transformId": "transformId",
"createdAt": "createdAt",
"updatedAt": "updatedAt",
"lastEventAt": "lastEventAt"
}
}Errors
Errors use application/problem+json. The code member is stable; branch on it rather than on title or detail.
4XXapplication/problem+jsonThe request was rejected.