API: Webhook Notifications

Webhook Notifications

Webhooks let your server receive real-time updates as exchange orders progress.

Setting Up Webhooks

Include a `webhook_url` when creating an exchange:

{
  "from": "BTC",
  "to": "XMR",
  "amount": "0.01",
  "address": "4Abc...",
  "rate_type": "float",
  "webhook_url": "https://yourserver.com/ghost-webhook"
}

Webhook Payload

We POST a JSON payload to your URL on every status change:

{
  "event": "order.status_changed",
  "order_id": "ord_7f8a9b2c",
  "status": "complete",
  "timestamp": "2026-05-10T10:18:00Z",
  "data": {
    "deposit_tx": "abc123...",
    "receive_tx": "def456...",
    "received_amount": "0.65432100"
  }
}

Event Types

Event	Triggered When
order.confirming	Deposit detected on-chain
order.exchanging	Swap processing started
order.sending	Outgoing tx broadcast
order.complete	Exchange finished
order.expired	Order timed out
order.refunding	Refund initiated

Webhook Security

Each webhook includes an HMAC signature in the header:

X-Ghost-Signature: sha256=abc123...

Verify this using your API key as the HMAC secret to ensure the webhook is genuine.

Retry Policy

—Failed webhooks are retried 3 times with exponential backoff (5s, 30s, 5min)
—Your endpoint must return HTTP 200 to acknowledge receipt
—After 3 failures, the webhook is marked as failed (check via API)