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

# Create webhook subscription

`POST /api/v1/webhooks`

## Request

- Base URL: `https://app.blueticked.com`
- URL: `https://app.blueticked.com/api/v1/webhooks`
- Auth: HTTP bearer

Subscribe an https endpoint to events. The API returns the signing secret only in this answer; an owner can show it again in the dashboard after a password check.

Store the secret: the API returns it only in this answer. An owner or admin can show it again in the dashboard (Developers → Webhooks, Show secret) after confirming it's them.

A retry with the same Idempotency-Key returns the same webhook without its `secret` field: the secret is shown once. If the first response was lost, rotate it, or have an owner show it again in the dashboard.

PATCH /api/v1/webhooks/{id} updates url/events/is_active, or pass rotate_secret: true to issue a new signing secret.

DELETE /api/v1/webhooks/{id} removes the subscription.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `url` string, required
  - `events` string[], required
  - `description` string

## Response `201`

Success

- object
  - `webhook` object, required
    - `description` string, nullable, required
    - `auto_disabled_at` string, nullable, required
    - `auto_disabled_reason` string, nullable, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `id` string, uuid, required
    - `url` string, required
    - `events` string[], required
    - `is_active` boolean, required
    - `secret` string
  - `request_id` string, required

## Other responses

- `400`: Validation failed
- `401`: Unauthorized: missing or invalid API key
- `402`: Insufficient wallet balance
- `403`: Forbidden: scope, plan limit, or suspension
- `404`: Not found
- `409`: Conflict (idempotency-key reuse or resource in use)
- `413`: Request body above the endpoint's size limit
- `422`: Understood but refused: the request is well-formed, the action is not permitted for this resource
- `429`: Rate limited
- `500`: Internal error
- `502`: An upstream provider refused or failed the request
- `503`: Channel or send queue unavailable

---

[API](https://skmtc.dev/blueticked/apis/blueticked-api.md) · [All operations](https://skmtc.dev/blueticked/apis/blueticked-api/llms.txt) · [OpenAPI document](https://skmtc.dev/blueticked/apis/blueticked-api/revisions/07132284f4ff?raw)