---
title: "Create webhook subscription"
method: POST
path: "/webhooks"
tags: ["webhooks"]
---

# Create webhook subscription

`POST /webhooks`

Creates a new webhook subscription to be actively notified on each change in the specified entities.

As part of subscription creation, Productboard validates the notification URL:
it must use `https`, have a publicly resolvable host, and not point to localhost,
loopback, site-local, or internal addresses.

**Scope requirements**: the OAuth2 application must have the scopes required by all requested event types.

## Request body

- WebhookCreateRequestBody — Request body for creating a webhook subscription.
  - `data` object, required
    - `fields` WebhookSubscriptionFields, required — Domain attributes for creating a webhook subscription.
      - `name` string, required — Human-readable label for this subscription.
      - `events` WebhookEvent[], required — Event types to subscribe to. At least one required; no duplicates allowed. The full list of supported values is defined in the `WebhookEventType` schema.
        - `eventType` 'feature.created' | 'feature.updated' | 'feature.deleted' | 'component.created' | 'component.updated' | 'product.created' | 'product.updated' | 'release.created' | 'release.updated' | 'release.deleted' | 'feature-release-assignment.updated' | 'hierarchy-entity.custom-field-value.updated' | 'note.created' | 'note.updated' | 'note.deleted' | 'insight.created' | 'insight.deleted' | 'key-result.created' | 'key-result.updated' | 'key-result.deleted' | 'objective.created' | 'objective.updated' | 'objective.deleted' | 'initiative.created' | 'initiative.updated' | 'initiative.deleted', required — Identifies the type of entity change that triggers a webhook notification.
      - `notification` WebhookNotificationConfig, required — Where and how Productboard sends notifications (used in create requests).
        - `url` string, uri, required — HTTPS endpoint to receive notifications. Requirements: - Must use `https` (encrypted) - Must be publicly reachable (no `localhost`, private IPs, or internal Kubernetes addresses)
        - `version` 1, required — Version of the notification payload structure. Currently only `1` is supported.
        - `headers` WebhookNotificationHeaders — Custom headers included in every outgoing request from Productboard to your endpoint (notifications). Use this to authenticate incoming requests.
          - `authorization` string — Raw value sent in the `Authorization` header. Supports any scheme: - `Basic aGVsbG86d29ybGQ=` - `Bearer <token>` - Any custom value

## Response `201`

Webhook subscription created successfully

- WebhookReferenceResponse — Response envelope for a newly created webhook subscription.
  - `data` WebhookReference, required — Lightweight reference returned after creating a webhook subscription.
    - `id` string, uuid, required — Unique identifier of the created webhook subscription.
    - `type` 'webhook', required — Resource type identifier for webhook subscriptions.
    - `links` object, required
      - `self` string, uri, required — URL to fetch the full webhook subscription.

## Other responses

- `400` — Bad Request - Invalid input format or malformed request
- `401` — Unauthorized - Missing or invalid authentication credentials
- `403` — Forbidden - Insufficient permissions
- `408` — Request Timeout - The server did not receive a complete request within the allowed time
- `422` — Unprocessable Entity - Validation failed (e.g., missing required fields, unknown fields)
- `429` — Too Many Requests - API rate limit exceeded, reduce request frequency and retry after the indicated time
- `500` — Internal Server Error - An unexpected error occurred on the server, please retry or contact support

---

[API](https://skmtc.dev/productboard/apis/notes.md) · [All operations](https://skmtc.dev/productboard/apis/notes/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/productboard/notes/revisions/b4004749b60f/schema)