---
title: "Create webhook subscription"
method: POST
path: "/v1/workspaces/{workspace_id}/webhooks"
tags: ["Webhooks"]
---

# Create webhook subscription

`POST /v1/workspaces/{workspace_id}/webhooks`

## Request

- Base URL: `https://api.blinq.me`
- URL: `https://api.blinq.me/v1/workspaces/{workspace_id}/webhooks`
- Auth: HTTP bearer

Available to any API-eligible account with a verified email address.

Stores a webhook subscription for your personal workspace or for a business workspace where you are an owner or admin. Business members and other workspaces return `404`. Business subscriptions belong to the workspace, not to the key owner, so other owners and admins can list and delete them.

In a business workspace, `contact.created` fires once for each new business contact shared into that workspace. Its `data.contact_id` is the business contact `id` returned by the list contacts endpoint. Updates, repeat shares, restores, and imported or backfilled history do not fire it, and events from before the subscription was created are not replayed.

The URL must be an absolute HTTPS URL without embedded credentials or a fragment. At least one event is required, and duplicate event names are stored once. No request is sent to the URL during registration.

Repeated calls create separate subscriptions, including for the same URL. Store the signing_secret returned on creation securely; it cannot be retrieved again. If the response is lost, delete the subscription and create a replacement.

Requires the `blinq:webhooks:write` and `blinq:contacts:read` scopes.

## Path parameters

- `workspace_id` string, required

## Request body

- object
  - `url` string, required: The HTTPS destination URL for deliveries. Credentials and fragments are rejected. The stored URL is the normalized form, preserving query parameters.
  - `events` string[], required: The events to receive. At least one is required; duplicates are stored once.

## Response `201`

The identity of the newly stored subscription.

- object: The identity of the newly stored subscription.
  - `id` string, required: The created subscription ID.
  - `signing_secret` string, required: Store this signing secret securely. It is returned only on creation and cannot be retrieved again.

## Other responses

- `400`: Bad request - Invalid query parameters or body. See `details` for each failing field
- `401`: Unauthorized - Missing or invalid API key
- `403`: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
- `404`: Not found - The workspace was not found, you are not its owner or admin, or access was denied
- `413`: Payload too large - The request body exceeds the maximum allowed size
- `415`: Unsupported media type - The request body must be `application/json`

---

[API](https://skmtc.dev/blinq/apis/blinq-public-api.md) - [All operations](https://skmtc.dev/blinq/apis/blinq-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/blinq/apis/blinq-public-api/revisions/2dedf4b14340?raw)