Refresh webhook signing secret

POST/v2/webhooks/{id}/secret

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

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.

Path ParametersExpand Collapse

id: string

Webhook unique identifier

Header ParametersExpand Collapse

"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"

One of the following:

"2026-01-01.nova"

"2025-12-12.clover"

ReturnsExpand Collapse

Webhook object { id, createdAt, description, 11 more }

id: string

Unique identifier

createdAt: string

ISO timestamp when the webhook was created

description: string

Optional description of the webhook purpose

health: object { avgResponseTime, consecutiveFailures, errorsSinceLastSuccess, 2 more }

avgResponseTime: number

Average response time in milliseconds

consecutiveFailures: number

Number of consecutive delivery failures

errorsSinceLastSuccess: number

Number of errors since last successful delivery

lastResponseTime: number

Last response time in milliseconds

lastSuccessAt: string

ISO timestamp of last successful delivery

lastStatus: object { code, message, timestamp }

Last delivery attempt status

code: number

HTTP status code from last delivery attempt

message: string

Status message from last delivery attempt

timestamp: string

ISO timestamp of last status update

name: string

Human-readable webhook name

object: "webhook"

Object type identifier

requestConfig: object { timeoutMs, headers }

timeoutMs: number

Request timeout in milliseconds (1000-30000)

minimum1000

maximum30000

headers: optional map[string]

Custom headers to send with webhook requests

secret: string

Webhook signing secret for verifying payloads

status: "active" or "paused" or "suspended"

Current status of the webhook

One of the following:

"active"

"paused"

"suspended"

topics: array of "post.created" or "post.updated" or "post.deleted" or 24 more

Array of event topics the webhook subscribes to

One of the following:

"post.created"

"post.updated"

"post.deleted"

"post.voted"

"ticket.created"

"ticket.updated"

"ticket.deleted"

"changelog.published"

"comment.created"

"comment.updated"

"comment.deleted"

"conversation.user.created"

"conversation.user.replied"

"conversation.admin.replied"

"conversation.admin.closed"

"conversation.handover_requested"

"conversation.admin.assigned"

"conversation.admin.noted"

"conversation.admin.snoozed"

"conversation.admin.unsnoozed"

"conversation.admin.opened"

"conversation.priority.updated"

"conversation.deleted"

"conversation.contact.attached"

"conversation.contact.detached"

"conversation.read"

"conversation_part.redacted"

updatedAt: string

ISO timestamp when the webhook was last updated

url: string

Webhook endpoint URL

version: string

API version for webhook payloads

Refresh webhook signing secret

curl https://do.featurebase.app/v2/webhooks/$ID/secret \
    -X POST \
    -H "Authorization: Bearer $FEATUREBASE_API_KEY"

{
  "id": "507f1f77bcf86cd799439011",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "description": "Handles all production events",
  "health": {
    "avgResponseTime": 200,
    "consecutiveFailures": 0,
    "errorsSinceLastSuccess": 0,
    "lastResponseTime": 150,
    "lastSuccessAt": "2025-01-15T10:30:00.000Z"
  },
  "lastStatus": {
    "code": 200,
    "message": "Success",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "name": "Production Webhook",
  "object": "webhook",
  "requestConfig": {
    "timeoutMs": 5000,
    "headers": {
      "X-Custom-Header": "value"
    }
  },
  "secret": "whsec_abc123def456ghi789",
  "status": "active",
  "topics": [
    "post.created",
    "post.updated"
  ],
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "url": "https://example.com/webhooks",
  "version": "1.0"
}

Returns Examples

{
  "id": "507f1f77bcf86cd799439011",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "description": "Handles all production events",
  "health": {
    "avgResponseTime": 200,
    "consecutiveFailures": 0,
    "errorsSinceLastSuccess": 0,
    "lastResponseTime": 150,
    "lastSuccessAt": "2025-01-15T10:30:00.000Z"
  },
  "lastStatus": {
    "code": 200,
    "message": "Success",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "name": "Production Webhook",
  "object": "webhook",
  "requestConfig": {
    "timeoutMs": 5000,
    "headers": {
      "X-Custom-Header": "value"
    }
  },
  "secret": "whsec_abc123def456ghi789",
  "status": "active",
  "topics": [
    "post.created",
    "post.updated"
  ],
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "url": "https://example.com/webhooks",
  "version": "1.0"
}