---
title: "Register a webhook (auth required; up to 3 per organization; https only)"
method: POST
path: "/api/rightos/webhooks"
tags: ["webhooks"]
---

# Register a webhook (auth required; up to 3 per organization; https only)

`POST /api/rightos/webhooks`

## Request

- Base URL: `https://rightos.i-s3.com`
- URL: `https://rightos.i-s3.com/api/rightos/webhooks`
- Auth: one of:
  - `apiKey` (a scheme the document does not define)
  - `bearer` (a scheme the document does not define)

Events token.verified / token.used / token.cancelled / token.transferred / queue.approaching are delivered as signed HTTPS POSTs (header x-rightos-signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, `${t}.${rawBody}`)>). The signing secret (whsec_...) is returned only once in this response and is never stored server-side. Delivery is best-effort: 3s timeout, no retries — respond 2xx immediately and process asynchronously. Private/internal hosts are rejected (SSRF protection).

## Request body

- object
  - `url` string, uri, required: https URL (http allowed for localhost only)
  - `events` WebhookEventType[]: Defaults to all four events

## Response `201`

Created. The secret is returned only once.

- object
  - `webhook` Webhook: Outbound webhook. The signing secret (whsec_...) is NOT stored server-side; it is derived from a master key and returned exactly once at registration.
    - `id` string, required
    - `organizationId` string, required
    - `url` string, uri, required
    - `events` WebhookEventType[], required
    - `createdAt` string, date-time, required
    - `lastDelivery` WebhookDeliveryResult: Most recent webhook delivery attempt.
      - `at` string, date-time, required
      - `event` 'token.verified' | 'token.used' | 'token.cancelled' | 'token.transferred' | 'queue.approaching', required: Outbound webhook event types. queue.approaching fires only when the location policy sets approachingThreshold (ADR-0029).
      - `ok` boolean, required
      - `status` integer: HTTP status (absent on connection failure or timeout)
      - `error` string: Short error description (no secrets)
    - `deliveredCount` integer
    - `failedCount` integer
  - `secret` string: Signing secret (whsec_...). Shown only once; not retrievable later.
  - `signatureHeader` string
  - `signatureFormat` string

## Other responses

- `400`: Invalid URL (non-https or internal host) or invalid events
- `402`: webhook_limit_reached (3 per organization)
- `403`: demo_org (demo organization cannot register webhooks)

---

[API](https://skmtc.dev/i-s3/apis/rightos-right-api.md) · [All operations](https://skmtc.dev/i-s3/apis/rightos-right-api/llms.txt) · [OpenAPI document](https://skmtc.dev/i-s3/apis/rightos-right-api/revisions/10020536e345?raw)