Skip to content
/Webhooks

Featurebase API (2026-01-01.nova)

Welcome to the Featurebase API. This API allows you to programmatically interact with your Featurebase organization.

This documentation reflects API version 2026-01-01.nova.

Download OpenAPI description
index.json
index.yaml
Overview
URL
https://featurebase.app
License
Proprietary
Languages
Servers
Mock server
https://docs.featurebase.app/_mock/rest-api/
Production
https://do.featurebase.app/

API Versioning

This API uses date-based versioning. Each version is identified by a release date and slug, e.g., 2026-01-01.nova.

Specifying a Version

Include the version in the request header:

Featurebase-Version: 2026-01-01.nova

Or set a default version for your organization in the dashboard settings.

Version Compatibility

  • Newer versions may add new fields to responses (always backwards-compatible)
  • Breaking changes (removed/renamed fields, changed behavior) only occur in new versions
  • Your integration will continue to work as long as you pin to a specific version

Authentication

All API requests require authentication via API key.

Include in headers:

Authorization: Bearer <api-key>

Create and manage your API keys in the Featurebase dashboard.

Error Handling

The API uses conventional HTTP response codes to indicate success or failure:

  • 2xx - Success
  • 4xx - Client errors (bad request, unauthorized, not found, etc.)
  • 5xx - Server errors (internal error)

Error Response Format

All errors follow a consistent format:

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "Post not found",
    "param": "id",
    "status": 404
  }
}

Error Types

TypeDescription
authentication_errorAuthentication failed (401)
authorization_errorPermission denied (403)
invalid_request_errorInvalid request parameters or resource not found (400, 404, 410)
api_errorServer-side error (500)
rate_limit_errorToo many requests (429)

Boards

Boards (post categories) organize feedback into distinct containers with their own settings.

Operations

Posts

User-submitted feedback and feature requests. Posts belong to boards and can be upvoted, commented on, and tracked through statuses.

Operations

Post Statuses

Post statuses define the workflow stages for posts (e.g., In Review, Active, Completed).

Operations

Comments

Threaded discussions on posts and changelogs. Comments support voting, moderation, and privacy controls.

Operations

Custom Fields

Configurable input fields for posts in your Featurebase organization. Custom fields allow you to collect additional structured data when users create posts.

Operations

Changelogs

Release notes and updates published by the organization. Changelogs keep users informed about new features, improvements, and fixes.

Operations

Admins

Team members who manage your Featurebase organization. Admins have roles that define their permissions.

Operations

Teams

Teams are groups within your Featurebase organization. Use this endpoint to list and retrieve team information for conversation assignment and organization management.

Operations

Contacts

Contacts are the customers and leads in your Featurebase organization. Use this endpoint to list and retrieve contact information.

Operations

Companies

Companies represent organizations or businesses that your users belong to. Use this endpoint to list and retrieve company information.

Operations

Surveys

Surveys allow you to collect targeted feedback from your users within your product. Surveys can be targeted to specific user segments or pages and can contain multiple questions with conditional logic.

Operations

Help Centers

Help centers allow organizations to create and manage knowledge bases with articles and collections. Currently, Featurebase supports one help center per organization.

Operations

Conversations

Conversations are messenger/inbox conversations in your Featurebase organization. Use this endpoint to list and retrieve conversation information.

Operations

Webhooks

Webhooks allow you to receive real-time HTTP callbacks when events occur in your Featurebase organization. Configure webhook endpoints to subscribe to specific event types.

Operations

List webhooks

Request

Returns a list of webhooks in your organization using cursor-based pagination.

Query Parameters

  • limit - Number of webhooks to return (1-100, default 10)
  • cursor - Cursor from previous response for pagination
  • status - Filter by status: "active", "paused", or "suspended"

Response Format

Returns a list object with:

  • object - Always "list"
  • data - Array of webhook objects
  • nextCursor - Cursor for the next page, or null if no more results

Webhook Object

Each webhook includes:

  • id - Unique webhook identifier
  • name - Human-readable webhook name
  • url - Webhook endpoint URL
  • topics - Array of subscribed event topics
  • status - Current status ("active", "paused", "suspended")
  • health - Health metrics (response times, error counts)
  • createdAt - Creation timestamp
  • updatedAt - Last update timestamp

Example

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

Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

Security
bearerAuth
Query
limitinteger[ 1 .. 100 ]

A limit on the number of objects to be returned, between 1 and 100.

Default 10
Example: limit=10
cursorstring<= 512 characters

An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page of results.

Example: cursor=eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9
statusstring

Filter webhooks by status

Enum"active""paused""suspended"
Example: status=active
Headers
Featurebase-Versionstring(FeaturebaseVersion)

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

Example: 2026-01-01.nova
curl -i -X GET \
  'https://docs.featurebase.app/_mock/rest-api/v2/webhooks?limit=10&cursor=eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9&status=active' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Featurebase-Version: 2026-01-01.nova'

Responses

Success

Bodyapplication/json
objectstringrequired

Object type identifier

Value"list"
Example: "list"
dataArray of objects(Webhook)required

Array of webhooks

Example: []
data[].​objectstringrequired

Object type identifier

Value"webhook"
Example: "webhook"
data[].​idstringrequired

Unique identifier

Example: "507f1f77bcf86cd799439011"
data[].​namestringrequired

Human-readable webhook name

Example: "Production Webhook"
data[].​urlstringrequired

Webhook endpoint URL

Example: "https://example.com/webhooks"
data[].​secretstringrequired

Webhook signing secret for verifying payloads

Example: "whsec_abc123def456ghi789"
data[].​descriptionstring or nullrequired

Optional description of the webhook purpose

Example: "Handles all production events"
data[].​topicsArray of stringsrequired

Array of event topics the webhook subscribes to

Items Enum"post.created""post.updated""post.deleted""post.voted""changelog.published""comment.created""comment.updated""comment.deleted"
Example: ["post.created","post.updated"]
data[].​statusstringrequired

Current status of the webhook

Enum"active""paused""suspended"
Example: "active"
data[].​requestConfigobject(WebhookRequestConfig)required
data[].​requestConfig.​timeoutMsinteger[ 1000 .. 30000 ]required

Request timeout in milliseconds (1000-30000)

Example: 5000
data[].​requestConfig.​headersobject

Custom headers to send with webhook requests

Example: {"X-Custom-Header":"value"}
data[].​lastStatusobject or null(WebhookLastStatus)required

Last delivery attempt status

data[].​lastStatus.​codeintegerrequired

HTTP status code from last delivery attempt

Example: 200
data[].​lastStatus.​messagestringrequired

Status message from last delivery attempt

Example: "Success"
data[].​lastStatus.​timestampstringrequired

ISO timestamp of last status update

Example: "2025-01-15T10:30:00.000Z"
data[].​healthobject(WebhookHealth)required
data[].​health.​lastResponseTimenumberrequired

Last response time in milliseconds

Example: 150
data[].​health.​avgResponseTimenumberrequired

Average response time in milliseconds

Example: 200
data[].​health.​lastSuccessAtstring or nullrequired

ISO timestamp of last successful delivery

Example: "2025-01-15T10:30:00.000Z"
data[].​health.​errorsSinceLastSuccessintegerrequired

Number of errors since last successful delivery

Example: 0
data[].​health.​consecutiveFailuresintegerrequired

Number of consecutive delivery failures

Example: 0
data[].​versionstringrequired

API version for webhook payloads

Example: "1.0"
data[].​createdAtstringrequired

ISO timestamp when the webhook was created

Example: "2025-01-15T10:30:00.000Z"
data[].​updatedAtstringrequired

ISO timestamp when the webhook was last updated

Example: "2025-01-15T10:30:00.000Z"
nextCursorstring or nullrequired

Cursor for fetching the next page (cursor-based pagination)

Example: "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
Response
application/json
{
  "object": "list",
  "data": [],
  "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
}

Create a webhook

Request

Creates a new webhook to receive event notifications.

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 post is created
  • post.updated - When a post is updated
  • post.deleted - When a post is deleted
  • post.voted - When a post receives a vote
  • 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.

Security
bearerAuth
Headers
Featurebase-Versionstring(FeaturebaseVersion)

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

Example: 2026-01-01.nova
Bodyapplication/json
namestring[ 1 .. 255 ] charactersrequired

Human-readable name for the webhook

Example: "Production Webhook"
urlstringrequired

Webhook endpoint URL (must be HTTPS)

Example: "https://example.com/webhooks"
descriptionstring<= 500 characters

Optional description of the webhook purpose

Example: "Handles all production events"
topicsArray of stringsnon-emptyrequired

Array of event topics to subscribe to

Items Enum"post.created""post.updated""post.deleted""post.voted""changelog.published""comment.created""comment.updated""comment.deleted"
Example: ["post.created","post.updated"]
requestConfigobject(WebhookRequestConfigInput)

Request configuration for webhook delivery

curl -i -X POST \
  https://docs.featurebase.app/_mock/rest-api/v2/webhooks \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Featurebase-Version: 2026-01-01.nova' \
  -d '{
    "name": "Production Webhook",
    "url": "https://example.com/webhooks",
    "description": "Handles all production events",
    "topics": [
      "post.created",
      "post.updated"
    ],
    "requestConfig": {
      "headers": {
        "X-Custom-Header": "value"
      }
    }
  }'

Responses

Created

Bodyapplication/json
objectstringrequired

Object type identifier

Value"webhook"
Example: "webhook"
idstringrequired

Unique identifier

Example: "507f1f77bcf86cd799439011"
namestringrequired

Human-readable webhook name

Example: "Production Webhook"
urlstringrequired

Webhook endpoint URL

Example: "https://example.com/webhooks"
secretstringrequired

Webhook signing secret for verifying payloads

Example: "whsec_abc123def456ghi789"
descriptionstring or nullrequired

Optional description of the webhook purpose

Example: "Handles all production events"
topicsArray of stringsrequired

Array of event topics the webhook subscribes to

Items Enum"post.created""post.updated""post.deleted""post.voted""changelog.published""comment.created""comment.updated""comment.deleted"
Example: ["post.created","post.updated"]
statusstringrequired

Current status of the webhook

Enum"active""paused""suspended"
Example: "active"
requestConfigobject(WebhookRequestConfig)required
requestConfig.​timeoutMsinteger[ 1000 .. 30000 ]required

Request timeout in milliseconds (1000-30000)

Example: 5000
requestConfig.​headersobject

Custom headers to send with webhook requests

Example: {"X-Custom-Header":"value"}
lastStatusobject or null(WebhookLastStatus)required

Last delivery attempt status

lastStatus.​codeintegerrequired

HTTP status code from last delivery attempt

Example: 200
lastStatus.​messagestringrequired

Status message from last delivery attempt

Example: "Success"
lastStatus.​timestampstringrequired

ISO timestamp of last status update

Example: "2025-01-15T10:30:00.000Z"
healthobject(WebhookHealth)required
health.​lastResponseTimenumberrequired

Last response time in milliseconds

Example: 150
health.​avgResponseTimenumberrequired

Average response time in milliseconds

Example: 200
health.​lastSuccessAtstring or nullrequired

ISO timestamp of last successful delivery

Example: "2025-01-15T10:30:00.000Z"
health.​errorsSinceLastSuccessintegerrequired

Number of errors since last successful delivery

Example: 0
health.​consecutiveFailuresintegerrequired

Number of consecutive delivery failures

Example: 0
versionstringrequired

API version for webhook payloads

Example: "1.0"
createdAtstringrequired

ISO timestamp when the webhook was created

Example: "2025-01-15T10:30:00.000Z"
updatedAtstringrequired

ISO timestamp when the webhook was last updated

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

Get webhook by ID

Request

Retrieves a single webhook by its unique identifier.

Path Parameters

  • id - The webhook ID (24-character ObjectId)

Response Format

Returns a webhook object with:

  • object - Always "webhook"
  • id - Unique webhook identifier
  • name - Human-readable webhook name
  • url - Webhook endpoint URL
  • description - Optional description
  • topics - Array of subscribed event topics
  • status - Current status ("active", "paused", "suspended")
  • requestConfig - Request configuration (timeout, headers)
  • lastStatus - Last delivery attempt status
  • health - Health metrics
  • createdAt - Creation timestamp
  • updatedAt - Last update timestamp

The response includes the webhook signing secret for payload verification.

Example

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

Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

Security
bearerAuth
Path
idstringrequired

Webhook unique identifier

Example: 507f1f77bcf86cd799439011
Headers
Featurebase-Versionstring(FeaturebaseVersion)

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

Example: 2026-01-01.nova
curl -i -X GET \
  https://docs.featurebase.app/_mock/rest-api/v2/webhooks/507f1f77bcf86cd799439011 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Featurebase-Version: 2026-01-01.nova'

Responses

Success

Bodyapplication/json
objectstringrequired

Object type identifier

Value"webhook"
Example: "webhook"
idstringrequired

Unique identifier

Example: "507f1f77bcf86cd799439011"
namestringrequired

Human-readable webhook name

Example: "Production Webhook"
urlstringrequired

Webhook endpoint URL

Example: "https://example.com/webhooks"
secretstringrequired

Webhook signing secret for verifying payloads

Example: "whsec_abc123def456ghi789"
descriptionstring or nullrequired

Optional description of the webhook purpose

Example: "Handles all production events"
topicsArray of stringsrequired

Array of event topics the webhook subscribes to

Items Enum"post.created""post.updated""post.deleted""post.voted""changelog.published""comment.created""comment.updated""comment.deleted"
Example: ["post.created","post.updated"]
statusstringrequired

Current status of the webhook

Enum"active""paused""suspended"
Example: "active"
requestConfigobject(WebhookRequestConfig)required
requestConfig.​timeoutMsinteger[ 1000 .. 30000 ]required

Request timeout in milliseconds (1000-30000)

Example: 5000
requestConfig.​headersobject

Custom headers to send with webhook requests

Example: {"X-Custom-Header":"value"}
lastStatusobject or null(WebhookLastStatus)required

Last delivery attempt status

lastStatus.​codeintegerrequired

HTTP status code from last delivery attempt

Example: 200
lastStatus.​messagestringrequired

Status message from last delivery attempt

Example: "Success"
lastStatus.​timestampstringrequired

ISO timestamp of last status update

Example: "2025-01-15T10:30:00.000Z"
healthobject(WebhookHealth)required
health.​lastResponseTimenumberrequired

Last response time in milliseconds

Example: 150
health.​avgResponseTimenumberrequired

Average response time in milliseconds

Example: 200
health.​lastSuccessAtstring or nullrequired

ISO timestamp of last successful delivery

Example: "2025-01-15T10:30:00.000Z"
health.​errorsSinceLastSuccessintegerrequired

Number of errors since last successful delivery

Example: 0
health.​consecutiveFailuresintegerrequired

Number of consecutive delivery failures

Example: 0
versionstringrequired

API version for webhook payloads

Example: "1.0"
createdAtstringrequired

ISO timestamp when the webhook was created

Example: "2025-01-15T10:30:00.000Z"
updatedAtstringrequired

ISO timestamp when the webhook was last updated

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