Webhooks overview

Webhooks push events to your backend the moment they happen — an order fills, a market resolves, a wallet balance changes — so you don’t have to poll for state that only Drazill knows.

Manage endpoints

Register an endpoint and the events you want in the developer dashboard, or over the API with a key that has the webhooks:write scope (reads need webhooks:read). Replace $KEY with your key.

$
# Create an endpoint subscribed to fills. The plaintext signing secret is
$
# returned ONCE, in the `secret` field — store it now; it is never shown again.
$
curl -sS https://api.drazill.com/api/v1/webhooks \
>
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
>
  -d '{"url":"https://your-app.example.com/hooks/drazill",
>
       "subscribed_events":["order.filled","trade.executed"]}'
$
$
# Send yourself a webhook.test delivery to confirm reachability.
$
curl -sS -X POST https://api.drazill.com/api/v1/webhooks/$ID/test -H "X-API-Key: $KEY"
$
$
# Rotate the signing secret (old + new both sign during a grace window).
$
curl -sS -X POST https://api.drazill.com/api/v1/webhooks/$ID/rotate-secret -H "X-API-Key: $KEY"
$
$
# Inspect deliveries and replay a failed one.
$
curl -sS https://api.drazill.com/api/v1/webhooks/$ID/deliveries -H "X-API-Key: $KEY"
$
curl -sS -X POST https://api.drazill.com/api/v1/webhooks/deliveries/$DELIVERY_ID/replay -H "X-API-Key: $KEY"

URL requirements. In production your URL must be https://. Hosts that resolve to private, loopback, link-local, or cloud-metadata addresses are rejected at registration and re-checked at delivery time (DNS-rebinding defense), and redirects are not followed.

The request Drazill sends

Each delivery is a POST with a compact, sorted-key JSON body (the signed bytes) and these headers:

Every delivery also carries Content-Type: application/json and User-Agent: Drazill-Webhooks/1.0.

The JSON body is the event envelope:

1
{
2
  "id": "…", "type": "order.filled", "version": "2026-05-08",
3
  "api_version": "v1", "livemode": true, "created_at": "…",
4
  "data": { "order_id": "…", "market_id": "…", "status": "FILLED", … },
5
  "request_id": null, "correlation_id": null
6
}

data carries only the fields declared by that event’s schema — payloads are validated against their schema and re-serialized before signing, so no internal or personal field can ever leak, and money is always a decimal string (never a float).

Read next