---
title: "Subscribe to market state-change webhooks"
method: POST
path: "/v5/webhooks/subscribe"
tags: ["Webhooks"]
---

# Subscribe to market state-change webhooks

`POST /v5/webhooks/subscribe`

## Request

- Base URL: `https://headlessoracle.com`
- URL: `https://headlessoracle.com/v5/webhooks/subscribe`
- Auth: API key in header `X-Oracle-Key`

Register a webhook URL to receive signed receipts when a market transitions between states (OPEN↔CLOSED, HALT). Builder+ plans only. Sandbox keys are rejected. Returns webhook_id and subscription_id.

## Request body

- object
  - `url` string, uri, required: HTTPS endpoint to receive webhook deliveries.
  - `mics` string[], required: MIC codes to subscribe to (e.g. ["XNYS","XNAS"]).
  - `events` string[]: Event types to subscribe to. Default: ["status_change"].

## Response `200`

Subscription created

- object
  - `webhook_id` string: Unique ID for this webhook. Use for DELETE /v5/webhooks/{webhook_id}.
  - `subscription_id` string: Legacy alias for webhook_id (backward compat).
  - `url` string
  - `mics` string[]

## Other responses

- `401`: Missing API key
- `402`: Sandbox keys cannot use webhooks — upgrade required
- `403`: Invalid API key or plan limit reached (builder=5, pro=25)

---

[API](https://skmtc.dev/headlessoracle/apis/headless-oracle.md) · [All operations](https://skmtc.dev/headlessoracle/apis/headless-oracle/llms.txt) · [OpenAPI document](https://skmtc.dev/headlessoracle/apis/headless-oracle/revisions/4e82fe332f29?raw)