Refresh webhook signing secret

client.webhooks.refreshSecret(, ?, ?): Webhook { id, createdAt, description, 11 more }

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.

ParametersExpand Collapse

id: string

Webhook unique identifier

params: WebhookRefreshSecretParams { featurebaseVersion }

featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"

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

One of the following:

"2026-01-01.nova"

"2025-12-12.clover"

ReturnsExpand Collapse

Webhook { id, createdAt, description, 11 more }

id: string

Unique identifier

createdAt: string

ISO timestamp when the webhook was created

description: string | null

Optional description of the webhook purpose

health: Health { 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 | null

ISO timestamp of last successful delivery

lastStatus: LastStatus | null

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: RequestConfig { timeoutMs, headers }

timeoutMs: number

Request timeout in milliseconds (1000-30000)

minimum1000

maximum30000

headers?: Record<string, string>

Custom headers to send with webhook requests

secret: string

Webhook signing secret for verifying payloads

status: "active" | "paused" | "suspended"

Current status of the webhook

One of the following:

"active"

"paused"

"suspended"

topics: Array<"post.created" | "post.updated" | "post.deleted" | 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

import Featurebase from 'featurebase-node';

const client = new Featurebase({
  apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted
});

const webhook = await client.webhooks.refreshSecret('507f1f77bcf86cd799439011');

console.log(webhook.id);

{
  "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"
}