---
title: "Register an outbound webhook endpoint (paid tiers)"
method: POST
path: "/v1/webhooks"
tags: ["webhooks"]
---

# Register an outbound webhook endpoint (paid tiers)

`POST /v1/webhooks`

Register a webhook for pair.created / spread.threshold. Free is 403'd (paid-tier gate); an org may hold
at most webhook_admin.MAX_ENDPOINTS_PER_ORG (3) endpoints (409 past that). The signing secret is returned
ONCE, here, in the 201 body — same reveal-once contract as POST /v1/keys (only its HMAC-equivalent, the
plaintext itself, is stored — see keys.generate_webhook_secret's docstring for why plaintext is correct
here, unlike an sk_live_ key). sync def (threadpooled IO).

## Headers

- `authorization` string

## Request body

- object

## Response `200`

Successful Response

- unknown

## Other responses

- `401` — Missing, malformed, or revoked API key
- `402` — Subscription inactive
- `422` — Validation Error
- `429` — Per-tier REST rps window (60s) OR monthly quota exceeded — body carries error plus tier/quota/count/window
- `503` — Auth admission gate full (transient) — retry shortly, see retry_after

---

[API](https://skmtc.net/dino/apis/dino-markets-api.md) · [All operations](https://skmtc.net/dino/apis/dino-markets-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/dino/dino-markets-api/revisions/8cbe8774824f/schema)