Skip to main content
Webhooks

Refresh webhook signing secret

Generates a new signing secret for a webhook. The previous secret is immediately invalidated.

POST
/v2/webhooks/{id}/secret

Path Parameters

  • id - The webhook ID (24-character ObjectId)

Response

Returns the updated webhook object, including the new signing secret.

Important

After refreshing the secret, any integrations that verify webhook signatures using the old secret will stop working until they are updated with the new secret.

Example Response

{
  "object": "webhook",
  "id": "507f1f77bcf86cd799439011",
  "name": "Production Webhook",
  "url": "https://example.com/webhooks",
  "secret": "whsec_newSecret123abc456def",
  "topics": ["post.created", "post.updated"],
  "status": "active",
  ...
}

Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Path Parameters

idstringrequired

Webhook unique identifier

Example: 507f1f77bcf86cd799439011

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover
Example: 2026-08-19.orbit

Response

application/json

Success

createdAtstringrequired

ISO timestamp when the webhook was created

Example: 2025-01-15T10:30:00.000Z
descriptionstring | nullrequired

Optional description of the webhook purpose

Example: Handles all production events
healthobjectrequired
idstringrequired

Unique identifier

Example: 507f1f77bcf86cd799439011
lastStatusobject | nullrequired

Last delivery attempt status

namestringrequired

Human-readable webhook name

Example: Production Webhook
objectenum<string>required

Object type identifier

Available options: webhook
Example: webhook
requestConfigobjectrequired
secretstringrequired

Webhook signing secret for verifying payloads

Example: whsec_abc123def456ghi789
statusenum<string>required

Current status of the webhook

Available options: active, paused, suspended
Example: active
topicsenum<string>[]required

Array of event topics the webhook subscribes to

updatedAtstringrequired

ISO timestamp when the webhook was last updated

Example: 2025-01-15T10:30:00.000Z
urlstringrequired

Webhook endpoint URL

Example: https://example.com/webhooks
versionstringrequired

API version for webhook payloads

Example: 1.0

Still need help? Ask the team