# Webhooks API

Subscribe HTTPS endpoints to k256 product events. Every delivery is HMAC-signed, retried with exponential backoff, and dead-lettered on persistent failure. Explore every endpoint, run them in-page, or point an AI agent at the MCP surface.

You are helping a user call this API. This document is the complete
contract: every endpoint, its parameters and request body, the auth, and
the MCP surface. Generate runnable `curl`/TypeScript/Python on demand
using the values below; replace the placeholder key with the user's real
`k256_live_` key.

- Base URL: `https://api.k256.xyz`
- Data plane: `https://api.k256.xyz/v1/webhooks`
- OpenAPI: `https://api.k256.xyz/webhooks/api/spec.json`
- MCP (for agents): `https://api.k256.xyz/webhooks/mcp` (server name `k256-gateway`) — the same operations as 1:1 tools.
- Auth: every request needs `Authorization: Bearer <YOUR_API_KEY>`. Never put the key in a URL query string.

Webhooks are HMAC-signed (per-destination signing secret). Verify the K256-Signature header before trusting a payload. HTTP receivers may expose it as k256-signature because header names are case-insensitive. Deliveries are at-least-once; dedupe on the event id.

## Endpoints

### `GET /v1/webhooks/subscriptions` — List webhook subscriptions
- Action: `read` · MCP tool: `webhooks.list_subscriptions`
- Query param `product` (string)
- Query param `status` (string)
- Query param `limit` (integer)
- Query param `cursor` (string)

### `POST /v1/webhooks/subscriptions` — Create a webhook subscription
- Action: `write` · MCP tool: `webhooks.create_subscription`
- Registers an event destination and returns the signing secret ONCE.
- Request body (JSON, required):
  - `product` — string
  - `url` — string (required)
  - `events` — string[] (required)
  - `name` — string
  - `description` — any | string | null
  - `replay_window_seconds` — integer

### `GET /v1/webhooks/subscriptions/{id}` — Get a webhook subscription
- Action: `read` · MCP tool: `webhooks.get_subscription`
- Path param `id` (string, required)

### `PATCH /v1/webhooks/subscriptions/{id}` — Update a webhook subscription
- Action: `write` · MCP tool: `webhooks.update_subscription`
- Path param `id` (string, required)
- Request body (JSON):
  - `url` — string
  - `events` — string[]
  - `name` — string
  - `description` — string | null
  - `replay_window_seconds` — integer
  - `status` — "active" | "disabled"

### `DELETE /v1/webhooks/subscriptions/{id}` — Delete a webhook subscription
- Action: `write` · MCP tool: `webhooks.delete_subscription`
- Path param `id` (string, required)

### `POST /v1/webhooks/subscriptions/{id}/rotate-secret` — Rotate a subscription's signing secret
- Action: `write` · MCP tool: `webhooks.rotate_secret`
- Begins a 24h rotation overlap and returns the new v2 secret ONCE.
- Path param `id` (string, required)

### `POST /v1/webhooks/subscriptions/{id}/test` — Send a test event to a subscription
- Action: `write` · MCP tool: `webhooks.test_subscription`
- Path param `id` (string, required)
- Request body (JSON, required):
  - `event_type` — string (required)
  - `data` — any

### `GET /v1/webhooks/subscriptions/{id}/stats` — Per-destination delivery stats
- Action: `read` · MCP tool: `webhooks.subscription_stats`
- Path param `id` (string, required)
- Query param `range` (string)

### `GET /v1/webhooks/subscriptions/{id}/deliveries` — List deliveries for a subscription
- Action: `read` · MCP tool: `webhooks.list_deliveries`
- Path param `id` (string, required)
- Query param `status` (string)
- Query param `event_type` (string)
- Query param `limit` (integer)
- Query param `cursor` (string)

### `GET /v1/webhooks/subscriptions/{id}/deliveries/{delivery_id}` — Get a delivery's full request/response
- Action: `read` · MCP tool: `webhooks.get_delivery`
- Path param `id` (string, required)
- Path param `delivery_id` (string, required)

### `POST /v1/webhooks/subscriptions/{id}/deliveries/{delivery_id}/resend` — Resend a delivery
- Action: `write` · MCP tool: `webhooks.resend_delivery`
- Path param `id` (string, required)
- Path param `delivery_id` (string, required)

### `GET /v1/webhooks/events` — List events
- Action: `read` · MCP tool: `webhooks.list_events`
- Query param `product` (string)
- Query param `type` (string)
- Query param `source` (string)
- Query param `limit` (integer)
- Query param `cursor` (string)

### `GET /v1/webhooks/events/{id}` — Get an event
- Action: `read` · MCP tool: `webhooks.get_event`
- Path param `id` (string, required)

### `POST /v1/webhooks/events/{id}/resend` — Re-fan-out an event
- Action: `write` · MCP tool: `webhooks.resend_event`
- Path param `id` (string, required)

### `GET /v1/webhooks/catalog` — List the event catalog
- Action: `read` · MCP tool: `webhooks.list_catalog`
- Query param `product` (string)

### `GET /v1/webhooks/catalog/{product}/{event_type}` — Get a catalog entry
- Action: `read` · MCP tool: `webhooks.get_catalog_entry`
- Path param `product` (string, required)
- Path param `event_type` (string, required)

### `GET /v1/webhooks/overview` — Org-level webhook KPIs
- Action: `read` · MCP tool: `webhooks.get_overview`

### `GET /v1/webhooks/alerts` — List health alerts
- Action: `read` · MCP tool: `webhooks.list_alerts`
- Query param `status` (string)
- Query param `limit` (integer)
- Query param `cursor` (string)

### `POST /v1/webhooks/alerts/{id}/ack` — Acknowledge an alert
- Action: `write` · MCP tool: `webhooks.ack_alert`
- Path param `id` (string, required)

### `GET /v1/webhooks/notification-settings` — List notification recipients
- Action: `read` · MCP tool: `webhooks.list_notification_settings`

### `POST /v1/webhooks/notification-settings` — Add or update a notification recipient
- Action: `write` · MCP tool: `webhooks.upsert_notification_settings`
- Request body (JSON, required):
  - `email` — string (required)
  - `min_severity` — "info" | "warning" | "critical"

### `POST /v1/webhooks/notification-settings/sync-admins` — Sync the WorkOS-admin notification fallback set
- Action: `write` · MCP tool: `webhooks.sync_admin_notifications`
- Request body (JSON, required):
  - `admins` — string[] (required)

### `DELETE /v1/webhooks/notification-settings/{id}` — Delete a manual notification recipient
- Action: `write` · MCP tool: `webhooks.delete_notification_settings`
- Path param `id` (string, required)