---
title: "Register a webhook"
method: POST
path: "/api/v1/webhooks"
tags: ["Webhooks"]
---

# Register a webhook

`POST /api/v1/webhooks`

## Request

- Base URL: `https://www.zen-mode.io`
- URL: `https://www.zen-mode.io/api/v1/webhooks`
- Auth: HTTP bearer

HTTPS only, on the standard port (443), with no credentials in the URL; the host must be public, and the URL is checked before it is stored and again at every delivery. Redirects from the endpoint are not followed. Deliveries carry `X-ZenMode-Signature` (hex HMAC-SHA256 of the exact raw request body, keyed with the webhook's `secret`) and `X-ZenMode-Event`. A `task.completed` or `task.failed` body is `{ event, data, timestamp }`, where `data.result` is the task's `result`. On a free or unconfirmed LinkedIn plan the connection request is sent without a note, and the task result carries `note_dropped: true` with `note_dropped_reason: "free_or_unconfirmed_plan"`. The webhook body carries the same two fields in `data.result`.

## Request body

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

## Response `201`

Registered. The response carries the signing `secret`, the only time this endpoint returns it; store it with your endpoint.

- object
  - `webhook` WebhookCreated
    - `id` integer, required
    - `url` string, required
    - `events` string[], required
    - `is_active` boolean
    - `created_at` string, date-time, nullable
    - `secret` string, required: Signing secret. Verify each delivery by computing HMAC-SHA256 of the raw body with this secret and comparing its hex digest to `X-ZenMode-Signature` in constant time. Returned only here; webhooks registered in the dashboard can reveal theirs there.

## Other responses

- `400`: Malformed JSON, a non-HTTPS or disallowed URL, or an unknown event name.
- `401`: Missing, malformed or invalid Authorization header, or an unknown API key.
- `403`: The key is valid but the account's plan does not include API access.
- `429`: Rate limit exceeded (100 requests/minute). Carries `Retry-After`.
- `500`: Unhandled server error.

---

[API](https://skmtc.dev/zen-mode/apis/zenmode-api.md) · [All operations](https://skmtc.dev/zen-mode/apis/zenmode-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zen-mode/apis/zenmode-api/revisions/2769372f1e3f?raw)