Create a webhook

POST/v2/webhooks

Creates a new webhook to receive event notifications.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Human-readable name (max 100 chars)
`url`	string	Yes	Webhook endpoint URL (must be HTTPS)
`description`	string	No	Optional description (max 500 chars)
`topics`	string[]	Yes	Event topics to subscribe to
`requestConfig`	object	No	Request configuration
`requestConfig.headers`	object	No	Custom 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

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.

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"

Body ParametersJSONExpand Collapse

name: string

Human-readable name for the webhook

minLength1

maxLength255

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

Array of event topics to subscribe 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"

url: string

Webhook endpoint URL (must be HTTPS)

description: optional string

Optional description of the webhook purpose

maxLength500

requestConfig: optional WebhookRequestConfigInput { headers }

Request configuration for webhook delivery

headers: optional map[string]

Custom headers to send with webhook requests (max 10)

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

Create a webhook

curl https://do.featurebase.app/v2/webhooks \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $FEATUREBASE_API_KEY" \
    -d '{
          "name": "Production Webhook",
          "topics": [
            "post.created",
            "post.updated"
          ],
          "url": "https://example.com/webhooks",
          "description": "Handles all production events"
        }'

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