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

# Subscribe a webhook

`POST /api/v1/webhooks`

## Request

- Base URL: `https://app.relaw.ai`
- URL: `https://app.relaw.ai/api/v1/webhooks`
- Auth: HTTP bearer

Registers an HTTPS URL to receive events. The same endpoints a
firm adds in Settings → API & Webhooks, exposed so Zapier (and
any other REST Hook client) can subscribe when a Zap turns on.

Idempotent on (firm, url, events): a retried subscribe returns
the existing row rather than creating a second delivery target.

The signing secret is returned only when a row is created. A
read-only key is enough — asking to be notified is not a write.

## Request body

- object
  - `url` string, uri, required: HTTPS only. `hookUrl` is accepted as an alias.
  - `hookUrl` string, uri: Alias for `url`.
  - `events` string[]: Empty or omitted means every event. Unknown names are dropped.
  - `description` string: Shown in Settings. e.g. 'Zapier: New Lead'.

## Response `200`

An identical subscription already existed.

- Webhook
  - `id` string, uuid, required
  - `object` 'webhook', required
  - `url` string, uri, required
  - `events` string[], required: Empty means every event type.
  - `description` string, nullable
  - `createdAt` string, date-time
  - `secret` string: Present only on create, never on a reused subscription. HMAC key for `relaw-signature`.

## Other responses

- `201`: A new endpoint was created. `secret` is present.
- `400`: Malformed request.
- `401`: Missing, malformed, revoked, or unknown API key.
- `429`: Over 120 requests per minute for this key. Honour the `Retry-After` header.

---

[API](https://skmtc.dev/relaw/apis/relaw-api.md) - [All operations](https://skmtc.dev/relaw/apis/relaw-api/llms.txt) - [OpenAPI document](https://skmtc.dev/relaw/apis/relaw-api/revisions/51a8e71983e0?raw)