Rotate a source token
POST/v1/sources/{sourceId}/rotate-tokenpreview
Replace a source’s token, and with it its URL. The old URL keeps working until the chosen expiry. Refused with 409 while a previous token is still active.
Path parameters
sourceIdstring RequiredA source ID, starting with src_.
Body
expirystring RequiredWhen the replaced URL stops working: immediately, or after 1h up to 7d.
Allowed values: "immediately", "1h", "2h", "4h", "8h", "12h", "24h", "3d", "7d"
Returns
The command completed.200
dataobject RequiredThe source and its whole URL, which is returned only by this operation.
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.
secretUrlstring RequiredThe source’s whole URL, token included. Give it to the provider. It’s returned only by this operation.
Example
curl -X POST "https://api.payloadpuffin.com/v1/sources/$SOURCEID/rotate-token" \
-H "Authorization: Bearer $PAYLOADPUFFIN_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"expiry":"immediately"}'{
"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",
"secretUrl": "secretUrl"
}
}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.