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

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

### Header Parameters

- `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"`

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

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

### Body Parameters

- `name: string`

  Human-readable name for the webhook

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

  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`

  Webhook endpoint URL (must be HTTPS)

- `description: optional string`

  Optional description of the webhook purpose

- `requestConfig: optional WebhookRequestConfigInput`

  Request configuration for webhook delivery

  - `headers: optional map[string]`

    Custom headers to send with webhook requests (max 10)

### Returns

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

    - `"webhook"`

  - `requestConfig: object { timeoutMs, headers }`

    - `timeoutMs: number`

      Request timeout in milliseconds (1000-30000)

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

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

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

```http
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"
        }'
```

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