# Webhooks

## List webhooks

`client.webhooks.list(WebhookListParamsparams?, RequestOptionsoptions?): CursorPage<Webhook>`

**get** `/v2/webhooks`

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

```json
{
  "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.

### Parameters

- `params: WebhookListParams`

  - `cursor?: string`

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

  - `limit?: number`

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

  - `status?: "active" | "paused" | "suspended"`

    Query param: Filter webhooks by status

    - `"active"`

    - `"paused"`

    - `"suspended"`

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

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

    - `"2026-01-01.nova"`

    - `"2025-12-12.clover"`

### Returns

- `Webhook`

  - `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: 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

    - `"webhook"`

  - `requestConfig: RequestConfig`

    - `timeoutMs: number`

      Request timeout in milliseconds (1000-30000)

    - `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

    - `"active"`

    - `"paused"`

    - `"suspended"`

  - `topics: Array<"post.created" | "post.updated" | "post.deleted" | 24 more>`

    Array of event topics the webhook subscribes to

    - `"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

### Example

```typescript
import Featurebase from 'featurebase-node';

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

// Automatically fetches more pages as needed.
for await (const webhook of client.webhooks.list()) {
  console.log(webhook.id);
}
```

#### Response

```json
{
  "data": [
    {
      "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"
    }
  ],
  "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9",
  "object": "list"
}
```

## Create a webhook

`client.webhooks.create(WebhookCreateParamsparams, RequestOptionsoptions?): 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

```json
{
  "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

```json
{
  "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.

### Parameters

- `params: WebhookCreateParams`

  - `name: string`

    Body param: Human-readable name for the webhook

  - `topics: Array<"post.created" | "post.updated" | "post.deleted" | 24 more>`

    Body param: Array of event topics to subscribe to

    - `"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`

    Body param: Webhook endpoint URL (must be HTTPS)

  - `description?: string`

    Body param: Optional description of the webhook purpose

  - `requestConfig?: WebhookRequestConfigInput`

    Body param: Request configuration for webhook delivery

    - `headers?: Record<string, string>`

      Custom headers to send with webhook requests (max 10)

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

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

    - `"2026-01-01.nova"`

    - `"2025-12-12.clover"`

### Returns

- `Webhook`

  - `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: 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

    - `"webhook"`

  - `requestConfig: RequestConfig`

    - `timeoutMs: number`

      Request timeout in milliseconds (1000-30000)

    - `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

    - `"active"`

    - `"paused"`

    - `"suspended"`

  - `topics: Array<"post.created" | "post.updated" | "post.deleted" | 24 more>`

    Array of event topics the webhook subscribes to

    - `"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

### Example

```typescript
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.create({
  name: 'Production Webhook',
  topics: ['post.created', 'post.updated'],
  url: 'https://example.com/webhooks',
});

console.log(webhook.id);
```

#### Response

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

## Get webhook by ID

`client.webhooks.retrieve(stringid, WebhookRetrieveParamsparams?, RequestOptionsoptions?): Webhook`

**get** `/v2/webhooks/{id}`

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

```json
{
  "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.

### Parameters

- `id: string`

  Webhook unique identifier

- `params: WebhookRetrieveParams`

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

    - `"2026-01-01.nova"`

    - `"2025-12-12.clover"`

### Returns

- `Webhook`

  - `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: 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

    - `"webhook"`

  - `requestConfig: RequestConfig`

    - `timeoutMs: number`

      Request timeout in milliseconds (1000-30000)

    - `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

    - `"active"`

    - `"paused"`

    - `"suspended"`

  - `topics: Array<"post.created" | "post.updated" | "post.deleted" | 24 more>`

    Array of event topics the webhook subscribes to

    - `"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

### Example

```typescript
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.retrieve('507f1f77bcf86cd799439011');

console.log(webhook.id);
```

#### Response

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

## Update a webhook

`client.webhooks.update(stringid, WebhookUpdateParamsparams, RequestOptionsoptions?): Webhook`

**patch** `/v2/webhooks/{id}`

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

### 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:

```json
{
  "status": "paused"
}
```

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

```json
{
  "status": "active"
}
```

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

### Example: Update Topics

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

### Example: Update Request Config

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

### Version Availability

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

### Parameters

- `id: string`

  Webhook unique identifier

- `params: WebhookUpdateParams`

  - `description?: string | null`

    Body param: Optional description of the webhook purpose (null to clear)

  - `name?: string`

    Body param: Human-readable name for the webhook

  - `requestConfig?: WebhookRequestConfigInput`

    Body param: Request configuration for webhook delivery

    - `headers?: Record<string, string>`

      Custom headers to send with webhook requests (max 10)

  - `status?: "active" | "paused"`

    Body param: Set to "active" to reactivate or "paused" to pause webhook delivery

    - `"active"`

    - `"paused"`

  - `topics?: Array<"post.created" | "post.updated" | "post.deleted" | 24 more>`

    Body param: Array of event topics to subscribe to

    - `"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`

    Body param: Webhook endpoint URL (must be HTTPS)

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

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

    - `"2026-01-01.nova"`

    - `"2025-12-12.clover"`

### Returns

- `Webhook`

  - `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: 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

    - `"webhook"`

  - `requestConfig: RequestConfig`

    - `timeoutMs: number`

      Request timeout in milliseconds (1000-30000)

    - `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

    - `"active"`

    - `"paused"`

    - `"suspended"`

  - `topics: Array<"post.created" | "post.updated" | "post.deleted" | 24 more>`

    Array of event topics the webhook subscribes to

    - `"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

### Example

```typescript
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.update('507f1f77bcf86cd799439011');

console.log(webhook.id);
```

#### Response

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

## Delete a webhook

`client.webhooks.delete(stringid, WebhookDeleteParamsparams?, RequestOptionsoptions?): WebhookDeleteResponse`

**delete** `/v2/webhooks/{id}`

Permanently deletes a webhook.

### Path Parameters

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

### Response

Returns a deletion confirmation object:

```json
{
  "id": "507f1f77bcf86cd799439011",
  "object": "webhook",
  "deleted": true
}
```

### Caution

This operation is **irreversible**. The webhook and its configuration will be permanently deleted.
After deletion, no events will be sent to the webhook endpoint.

### Version Availability

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

### Parameters

- `id: string`

  Webhook unique identifier

- `params: WebhookDeleteParams`

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

    - `"2026-01-01.nova"`

    - `"2025-12-12.clover"`

### Returns

- `WebhookDeleteResponse`

  - `id: string`

    Unique identifier of the deleted webhook

  - `deleted: true`

    Indicates the resource was deleted

    - `true`

  - `object: "webhook"`

    Object type identifier

    - `"webhook"`

### Example

```typescript
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.delete('507f1f77bcf86cd799439011');

console.log(webhook.id);
```

#### Response

```json
{
  "id": "507f1f77bcf86cd799439011",
  "deleted": true,
  "object": "webhook"
}
```

## Refresh webhook signing secret

`client.webhooks.refreshSecret(stringid, WebhookRefreshSecretParamsparams?, RequestOptionsoptions?): Webhook`

**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

```json
{
  "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.

### Parameters

- `id: string`

  Webhook unique identifier

- `params: WebhookRefreshSecretParams`

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

    - `"2026-01-01.nova"`

    - `"2025-12-12.clover"`

### Returns

- `Webhook`

  - `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: 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

    - `"webhook"`

  - `requestConfig: RequestConfig`

    - `timeoutMs: number`

      Request timeout in milliseconds (1000-30000)

    - `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

    - `"active"`

    - `"paused"`

    - `"suspended"`

  - `topics: Array<"post.created" | "post.updated" | "post.deleted" | 24 more>`

    Array of event topics the webhook subscribes to

    - `"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

### Example

```typescript
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);
```

#### Response

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

## Domain Types

### Webhook

- `Webhook`

  - `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: 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

    - `"webhook"`

  - `requestConfig: RequestConfig`

    - `timeoutMs: number`

      Request timeout in milliseconds (1000-30000)

    - `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

    - `"active"`

    - `"paused"`

    - `"suspended"`

  - `topics: Array<"post.created" | "post.updated" | "post.deleted" | 24 more>`

    Array of event topics the webhook subscribes to

    - `"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

### Webhook Request Config Input

- `WebhookRequestConfigInput`

  Request configuration for webhook delivery

  - `headers?: Record<string, string>`

    Custom headers to send with webhook requests (max 10)

### Webhook Delete Response

- `WebhookDeleteResponse`

  - `id: string`

    Unique identifier of the deleted webhook

  - `deleted: true`

    Indicates the resource was deleted

    - `true`

  - `object: "webhook"`

    Object type identifier

    - `"webhook"`