---
title: "Register a webhook endpoint"
method: POST
path: "/v1/webhooks"
---

# Register a webhook endpoint

`POST /v1/webhooks`

## Request

- Base URL: `https://api.reqbeat.com`
- URL: `https://api.reqbeat.com/v1/webhooks`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Register a webhook delivery target -- `secret` is stored as the
endpoint's HMAC signing key, scoped to the caller's own customer, and
never logged.

Idempotent on (customer, url): re-registering the same target returns
the SAME id rather than a second row, so a retrying caller ends up with
one endpoint it can hand straight to `POST /v1/watches`. Omitted
`secret` is generated server-side and returned once, in `secret`.

Requires the `webhooks` scope.

## Request body

- CreateWebhookRequest: `secret` is optional (signalsapi-3806): an agent holding only an API key has no signing key to offer, and requiring one made the watch surface uncallable for exactly the caller class it exists to serve. A caller that wants to verify `X-Reqbeat-Signature` still supplies its own.
  - `url` string, required
  - `secret` string, nullable

## Response `201`

Successful Response

- CreateWebhookResponse: `created` is `False` on the idempotent re-registration branch. `secret` is non-null ONLY when the server generated it on THIS call (the request omitted one and a fresh row was created) -- the one moment it is ever disclosed (NFR-S3); every other case, including re-registration and a caller-supplied secret, returns `null`.
  - `id` integer, required
  - `url` string, required
  - `created` boolean, required
  - `secret` string, nullable

## Other responses

- `401`: No API key was sent.
- `403`: The presented key is invalid or revoked, or (see `x-required-scope` on this operation) it does not carry the scope this operation requires.
- `422`: Validation Error

---

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