Webhooks (API)

OwlViz delivers **monitor** and **market** change events to your HTTPS endpoint with HMAC-SHA256 signing and at-least-once retries.

API routes (v1)

Method	Path	Auth
`POST`	`/v1/webhooks`	API key (`ov_live_…`, Builder+ quota) or ops admin
`GET`	`/v1/webhooks`	API key or admin
`GET`	`/v1/webhooks/:id`	API key or admin
`PATCH`	`/v1/webhooks/:id`	API key or admin
`DELETE`	`/v1/webhooks/:id`	API key or admin
`POST`	`/v1/webhooks/:id/test`	API key or admin
`GET`	`/v1/webhooks/:id/deliveries`	API key or admin

OpenAPI tag: **Automation**. Create payloads accept url, events (monitor types, market types, *, or webhook.test), and optional filters.collectionAddress.

Subscribe (curl)

bash

curl -sS -X POST "$OWLVIZ_API_BASE/v1/webhooks" \
  -H "Authorization: Bearer $OWLVIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example/webhooks/owlviz",
    "events": ["spot_floor_changed", "reference_floor_changed"],
    "filters": { "collectionAddress": "YOUR_COLLECTION" }
  }'

The signing secret is returned once on create — store it securely.

Verification & payloads

Delivery contract, signature algorithm, dedupe keys, and retry classification:

[Webhook delivery & signature verification](../webhooks.md) (canonical deep dive)
[Monitoring — webhooks](./monitoring.md#webhooks)
Example consumer: [examples/webhook-consumer](../../examples/webhook-consumer/)

The TypeScript SDK focuses on read/automation discovery in this sprint; use fetch or your HTTP client for webhook CRUD until SDK webhook helpers land in a future sprint.