Rotate webhook signing secret

POST

/v1/webhooks/{webhook_id}/rotate-secret

const rotated = await bird.webhooks.rotateSecret(
  "whk_01krdgeqcxet5s7t44vh8rt9mg",
);
console.log(rotated.secret);

rotated = client.webhooks.rotate_secret("whk_01krdgeqcxet5s7t44vh8rt9mg")
print(rotated.secret)

rotated, err := client.Webhooks.RotateSecret(context.Background(), "whk_123")
if err != nil {
	log.Fatal(err)
}
fmt.Println(rotated.Secret)

$rotated = $bird->webhooks->rotateSecret('whk_01krdgeqcxet5s7t44vh8rt9mg');
echo $rotated->getSecret();

bird webhooks rotate-secret <webhook-id> --yes

curl -X POST "https://us1.platform.bird.com/v1/webhooks/{webhook_id}/rotate-secret" \
  -H "Authorization: Bearer $TOKEN"

响应200

{
  "secret": "whsec_newbase64encodedvalue"
}

Generates a new signing secret for the endpoint and returns it exactly once: store it immediately, it cannot be retrieved after this response. For 24 hours every delivery is signed with both the old and the new secret, so a receiver verifying with either keeps working while you roll the new one out. After the window the old secret stops signing. Verification details are in the webhooks guide.

An endpoint holds at most 5 concurrently valid secrets, so rotating repeatedly within the overlap window fails with WebhookTooManySecrets until an older secret expires.

参数

webhook_id

string

ID of the webhook endpoint (whk_ prefix), as returned when it was created.

响应载荷

secret

string

必填

The new signing secret (whsec_ prefix). Shown only in this response: store it immediately, it cannot be retrieved again. Deliveries are signed with both this and the previous secret for 24 hours after rotation, then the previous secret stops signing.

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Watch the guideWebhooks done right: reliable delivery events Understand the conceptHow do I verify a webhook signature?Follow the learning pathOperate messaging reliably

Try the practice and get an implementation brief

const rotated = await bird.webhooks.rotateSecret(
  "whk_01krdgeqcxet5s7t44vh8rt9mg",
);
console.log(rotated.secret);

rotated = client.webhooks.rotate_secret("whk_01krdgeqcxet5s7t44vh8rt9mg")
print(rotated.secret)

rotated, err := client.Webhooks.RotateSecret(context.Background(), "whk_123")
if err != nil {
	log.Fatal(err)
}
fmt.Println(rotated.Secret)

$rotated = $bird->webhooks->rotateSecret('whk_01krdgeqcxet5s7t44vh8rt9mg');
echo $rotated->getSecret();

bird webhooks rotate-secret <webhook-id> --yes

curl -X POST "https://us1.platform.bird.com/v1/webhooks/{webhook_id}/rotate-secret" \
  -H "Authorization: Bearer $TOKEN"

响应200

{
  "secret": "whsec_newbase64encodedvalue"
}