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

# Register a webhook

`POST /v1/webhooks/register`

## Request

- Base URL: `https://zarq.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://zarq.ai/v1/webhooks/register`
- Auth: none declared

Register a webhook URL for risk event notifications.

Payload is delivered via HTTP POST with:
- X-ZARQ-Event: event type
- X-ZARQ-Signature: sha256=<hmac> (if secret provided)
- X-ZARQ-Delivery: unique delivery ID
- X-ZARQ-Attempt: attempt number (1, 2, 3)

Retry: 3 attempts with exponential backoff (5s, 25s, 125s).
Failed deliveries stored in dead letter queue.

## Request body

- WebhookRegisterRequest
  - `url` string, required: Your endpoint URL (HTTPS recommended)
  - `events` string[], required: Event types to subscribe to
  - `secret` string, nullable: HMAC-SHA256 signing secret
  - `metadata` object, nullable: Arbitrary metadata

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/zarq/apis/zarq-nerq.md) · [All operations](https://skmtc.dev/zarq/apis/zarq-nerq/llms.txt) · [OpenAPI document](https://skmtc.dev/zarq/apis/zarq-nerq/revisions/adc2843b9273?raw)