---
title: "Create a webhook"
method: POST
path: "/v2/webhooks/{teamId}"
---

# Create a webhook

`POST /v2/webhooks/{teamId}`

Registers a webhook and enqueues an asynchronous verification handshake (run by the dispatcher). The response includes the signing `secret`, shown only this once; `verified` is false until the handshake passes.

## Path parameters

- `teamId` string, uuid, required

## Request body

- WebhookCreate — On create, the dispatcher asynchronously runs a verification handshake: it sends a GET to `url` with `micro_hook_mode=subscribe`, a one-time `micro_hook_challenge`, and the webhook's `micro_hook_token`. The endpoint must respond 200 and echo the challenge value verbatim in the body; on success the webhook's `verified` flag flips to true. A failed handshake does not fail creation — re-run it later via the verify endpoint.
  - `name` string, required
  - `url` string, uri, required — HTTP(S) endpoint. Rejected if it resolves to a private/internal address.
  - `description` string, nullable
  - `enabled` boolean

## Response `201`

The created webhook, including its one-time signing secret.

- WebhookWithSecret — A registered webhook endpoint.
  - `id` string, uuid, required
  - `name` string, required
  - `description` string, nullable
  - `url` string, uri, required — Endpoint events are delivered to.
  - `team_id` string, uuid, required
  - `enabled` boolean, required — Disabled webhooks are skipped at delivery time.
  - `verified` boolean, required — True once the endpoint has completed the verification handshake.
  - `verified_at` string, date-time, nullable
  - `verification_token` string — Stable token replayed to the endpoint (as the `micro_hook_token` query param) during the verification handshake. The endpoint may check it to confirm the request originated from Micro.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, nullable
  - `secret` string, required — HMAC signing secret (prefix `whsec_`). Store it now — it is never returned again. The dispatcher signs each delivered payload with it so your endpoint can verify authenticity.
  - `verification` WebhookVerification — Status of the verification handshake enqueued by this request. The handshake runs asynchronously in the dispatcher; poll the webhook (its `verified` flag flips to true on success) to observe the outcome.
    - `status` 'pending', required — Always `pending` at the moment of the response — the dispatcher has been asked to run the handshake but has not reported back yet.

## Other responses

- `400` — Request validation failed. Inspect `error.errors` for field-level details.
- `401` — Missing or invalid credentials.
- `403` — Authenticated but not permitted to perform this action.
- `409` — Request conflicts with current state (e.g., duplicate or stale write).

---

[API](https://skmtc.net/micro-so/apis/prism.md) · [All operations](https://skmtc.net/micro-so/apis/prism/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/micro-so/prism/versions/558afa74332e/schema)