Find something... ⌘K

Orders / Follow an order

Webhooks

Webhooks tell your server when an order changes, so your records stay right when no user is watching. Maxy sends one signed order.updated event for each change of state or btcTxId, within about 15 seconds.

Register an endpoint

Register your HTTPS endpoint once. The answer carries the signing secret, once: store it. BASE and KEY are as on Get a quote. A URL that is not HTTPS on a public host answers invalid_input, and a sixth endpoint answers conflict: delete one first with DELETE /webhooks/{id}.

curlTypeScriptPython
Copy
curl -s -X POST "$BASE/webhooks" \ -H "x-maxy-key: $MAXY_API_KEY" -H "content-type: application/json" \ -d '{ "url": "https://your.app/maxy/webhooks" }'
  • Answer 2xx within 10 seconds. Otherwise Maxy retries 8 times over about 23 hours.
  • Delivery is at least once: process each event id once.
  • Two events can arrive out of order: order them by createdAt.
  • Maxy sends events for orders placed with your key, until the order ends, or for 3 days. POST /orders/watch adds any other order.
  • POST /webhooks/{id}/test sends a signed test event. POST /webhooks/{id}/events/{eventId}/replay resends one. GET /webhooks/{id}/events lists the last 25.

On a laptop, with no tunnel: npx maxy webhooks listen --forward-to http://localhost:3000/maxy/webhooks.

Verify a webhook

Check every event's signature before you trust it, so nobody else can fake one. Maxy-Signature is t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of <t>.<raw body>, keyed with the endpoint secret. alreadyProcessed and recordOrderState are yours.

TypeScriptPython
Copy
import express from 'express'; import { verifyWebhook, type MaxyWebhookEvent } from '@maxy-labs/sdk'; const app = express(); app.post('/maxy/webhooks', express.raw({ type: 'application/json' }), async (req, res) => { let event: MaxyWebhookEvent; try { event = await verifyWebhook(req.body.toString(), req.header('maxy-signature'), process.env.MAXY_WEBHOOK_SECRET!); } catch { return res.sendStatus(400); // a bad or stale signature: not from Maxy, or a replay } // Your own store: deliveries repeat, so dedupe on the event id. if (await alreadyProcessed(event.id)) return res.sendStatus(200); if (event.type === 'order.updated') await recordOrderState(event.data.orderId, event.data.state, event.data.btcTxId); res.sendStatus(200); });

Verify the raw body before you parse it, compare in constant time, and reject a t more than 5 minutes from now.

Test your verifier against the published vector, webhook-test-vector.json in your kit's examples folder, at the vector's own time: it must accept the vector, refuse it with one byte changed, and refuse it at t + 301. verify-webhook.mjs and verify_webhook.py in the same folder check all three. If a secret leaks, delete the endpoint and create a new one.

Event fields

FieldTypeMeaning
idstringThe event id, evt_ and 24 hex digits. Dedupe on it
typestringorder.updated or webhook.test
createdAtstringWhen the event was made, RFC 3339 in UTC
dataobjectBelow
sandboxbooleantrue on a sandbox event; absent on a live one

data carries the order, as GET /status returns it, plus previousState:

FieldTypeMeaning
orderIdstringThe order id
routestringevm-btc-escrow, evm-btc-gasless, btc-evm, sol-btc, btc-sol or cross-evm
chainIdnumber or nullThe EVM chain the order was paid on
statestringOne of the nine states
previousStatestring or nullThe state Maxy reported before this one
rawStatusstringThe solver's own status, for support
isCompletebooleantrue in a final state
btcTxIdstring or nullThe Bitcoin payment, once sent
txsarray{ label, hash } for each transaction of the order
sandbox, scenarioOn sandbox events only

POST /webhooks/{id}/test sends a webhook.test event instead, with webhookId and message.