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

# Register a webhook

`POST /client/webhooks`

## Request

- Base URL: `https://api.roar-ai.com`
- URL: `https://api.roar-ai.com/client/webhooks`
- Auth: HTTP bearer

Returns an HMAC signing secret ONCE. Subscribe to named events or to `["*"]`. Requires `webhooks:write`.

## Request body

- CreateWebhookRequest
  - `url` string, uri, required: Public https endpoint
  - `events` WebhookSubscription[]
  - `description` string

## Response `201`

The created webhook (secret shown once)

- CreatedWebhook
  - `id` string, uuid, required
  - `url` string, uri, required
  - `events` WebhookSubscription[], required
  - `description` string, nullable, required
  - `enabled` boolean, required
  - `createdAt` string, date-time, required
  - `secret` string, required: HMAC signing secret — shown once
  - `warning` string, required

## Other responses

- `400`: Invalid or unsafe URL
- `403`: Key lacks webhooks:write

---

[API](https://skmtc.dev/roar-ai/apis/roar-ai-api.md) · [All operations](https://skmtc.dev/roar-ai/apis/roar-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/roar-ai/apis/roar-ai-api/revisions/37e4d0d5a7fe?raw)