Skip to main content
Webhooks

Create a webhook

Creates a new webhook to receive event notifications.

POST
/v2/webhooks

Request Body

FieldTypeRequiredDescription
namestringYesHuman-readable name (max 100 chars)
urlstringYesWebhook endpoint URL (must be HTTPS)
descriptionstringNoOptional description (max 500 chars)
topicsstring[]YesEvent topics to subscribe to
requestConfigobjectNoRequest configuration
requestConfig.headersobjectNoCustom headers to send (max 10)

Available Topics

  • post.created - When a new feedback post is created
  • post.updated - When a feedback post is updated
  • post.deleted - When a feedback post is deleted
  • post.voted - When a feedback post receives a vote
  • ticket.created - When a new ticket is created
  • ticket.updated - When a ticket is updated
  • ticket.deleted - When a ticket is deleted
  • changelog.published - When a changelog is published
  • comment.created - When a comment is created
  • comment.updated - When a comment is updated
  • comment.deleted - When a comment is deleted
  • audit_log.created - When an audit log event is recorded (requires Enterprise plan)

Response

Returns the created webhook object including the signing secret.

Example Request

{
  "name": "Production Webhook",
  "url": "https://example.com/webhooks",
  "description": "Handles all production events",
  "topics": ["post.created", "post.updated", "comment.created"],
  "requestConfig": {
    "timeoutMs": 10000,
    "headers": {
      "X-Custom-Header": "value"
    }
  }
}

Example Response

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

Limits

Each organization has a maximum number of webhooks (default: 10). Creating a webhook when the limit is reached will return a 400 error.

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_...

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

application/json
descriptionstring

Optional description of the webhook purpose

Maximum string length: 500
Example: Handles all production events
namestringrequired

Human-readable name for the webhook

Required string length: 1 - 255
Example: Production Webhook
requestConfigobject

Request configuration for webhook delivery

topicsenum<string>[]required

Array of event topics to subscribe to

Minimum array length: 1
urlstringrequired

Webhook endpoint URL (must be HTTPS)

Example: https://example.com/webhooks

Response

application/json

Created

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