Webhooks

Update a webhook

Updates a webhook's properties. Supports partial updates - only provided fields will be updated.

PATCH

/v2/webhooks/{id}

Update a webhook

curl --request PATCH \
  --url https://do.featurebase.app/v2/webhooks/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Featurebase-Version: 2026-08-19.orbit' \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "Handles all production events",
  "name": "Production Webhook",
  "requestConfig": {
    "headers": {
      "X-Custom-Header": "value"
    }
  },
  "status": "active",
  "topics": [
    "post.created",
    "post.updated"
  ],
  "url": "https://example.com/webhooks"
}
'

{
  "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"
  },
  "id": "507f1f77bcf86cd799439011",
  "lastStatus": {
    "code": 200,
    "message": "Success",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "name": "Production Webhook",
  "object": "webhook",
  "requestConfig": {
    "headers": {
      "X-Custom-Header": "value"
    },
    "timeoutMs": 5000
  },
  "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"
}

Path Parameters

id - The webhook ID (24-character ObjectId)

Request Body

All fields are optional. Only provided fields will be updated.

Field	Type	Description
`name`	string	Human-readable name (max 100 chars)
`url`	string	Webhook endpoint URL (must be HTTPS)
`description`	string/null	Description (null to clear)
`topics`	string[]	Event topics to subscribe to
`status`	string	"active" to reactivate, "paused" to pause delivery
`requestConfig`	object	Request configuration
`requestConfig.headers`	object	Custom headers to send (max 10)

Pausing and Reactivating Webhooks

You can pause a webhook to temporarily stop receiving events:

{
  "status": "paused"
}

Webhooks may also be automatically paused or suspended due to delivery failures. To reactivate:

{
  "status": "active"
}

Reactivating a webhook resets the health metrics and allows it to receive events again.

Example: Update Topics

{
  "topics": ["post.created", "post.updated", "post.deleted"]
}

Example: Update Request Config

{
  "requestConfig": {
    "headers": {
      "X-Custom-Header": "new-value"
    }
  }
}

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

Body

descriptionstring | null

Optional description of the webhook purpose (null to clear)

Maximum string length: 500

Example: Handles all production events

namestring

Human-readable name for the webhook

Required string length: 1 - 255

Example: Production Webhook

requestConfigobject

Request configuration for webhook delivery

Show child attributes

statusenum<string>

Set to "active" to reactivate or "paused" to pause webhook delivery

Available options: active, paused

Example: active

topicsenum<string>[]

Array of event topics to subscribe to

Minimum array length: 1

urlstring

Webhook endpoint URL (must be HTTPS)

Example: https://example.com/webhooks

Response

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

Show child attributes

idstringrequired

Unique identifier

Example: 507f1f77bcf86cd799439011

lastStatusobject | nullrequired

Last delivery attempt status

Show child attributes

namestringrequired

Human-readable webhook name

Example: Production Webhook

objectenum<string>required

Object type identifier

Available options: webhook

Example: webhook

requestConfigobjectrequired

Show child attributes

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