Webhooks
Connect a URL, verify the signature, and acknowledge with the exact body success.
Connect
Webhooks are how your CRM learns that an order or payout changed. The portal cookie cannot call /v1, and the popup cannot settle an invoice. Your server receives a POST, checks the signature, then replies success.
- The workspace must be active. An owner signs in at the dashboard and creates a key under Settings → Developer. Inactive workspaces reject API calls with
40100. - Expose an HTTPS endpoint that accepts
POSTand reads the raw body. The URL must be reachable from the Bytix API. - Paste that URL under Settings → Notifications and save it. This is the default destination for every order and payout.
- Choose Rotate secret and copy the signing secret into server env before you leave the page. It is shown once. Saving the URL does not reveal the secret again.
- Optional: if your CRM has a separate endpoint for payouts, also save a Payout webhook URL. Payout events go there; order events stay on the main URL. Both are signed with the same secret.
- Optional: pass
callback_urlon create order or create payout. That URL is used for that row only. The signing secret is still the one from Notifications.
Test
After the URL is saved, use Send test on Notifications. We POST webhook.test to the saved URL with the same headers as a real event. A row appears under Recent deliveries:
| Status | Meaning |
|---|---|
delivered | HTTP 2xx and the body was success |
failed | The request errored, or the ack was not success. The response snippet is stored. |
skipped | No URL was configured for that event |
A failed delivery is retried automatically (see Retry). After fixing the handler you can also use Retry on that row to send it again at once.
Events
| Event | When |
|---|---|
order.paid | The total received is within your underpay and overpay tolerance of the quote, or a review was accepted |
order.paid_partial | Part of the quote arrived and the timer is still running: the payer can send the rest |
order.paid_over | An overpayment past your overpay tolerance was accepted in review |
order.review | Still short when the timer ended, over the overpay tolerance, or the wrong network or token. The funds are recorded as received; do not fulfil yet |
order.expired | Timer elapsed while still open |
order.cancelled | Payer cancelled checkout |
payout.awaiting_approval | Customer withdrawal created; the amount is held until it is approved |
payout.pending | Approved (by the merchant, or automatically under your limit); being sent |
payout.rejected | Merchant rejected the payout; the held amount returns to the balance |
payout.submitted | Withdrawal accepted and sent on-chain |
payout.completed | On-chain payout confirmed |
payout.failed | Payout failed; the held amount returns to the balance |
webhook.test | Send test from Settings → Notifications. Not a payment. |
Destination is callback_url on the order or payout, else (payout events) the payout webhook URL, else the webhook URL saved under Notifications. Headers: X-Bytix-Event, X-Bytix-Signature. Content type is application/json. We POST once per status change — not once per on-chain transfer.
Ack
HTTP/1.1 200 OK
Content-Type: text/plain
successHTTP must be 2xx and the body must be exactly success (trimmed, case-insensitive). JSON such as { "ok": true } is a failure. We store the first 2,000 characters of the response as the error.
Signature
HMAC-SHA256 of the using your webhook secret. Compare the hex digest in constant time. Prefer the raw request bytes; re-serializing a parsed object can change key order and fail verification.
const crypto = require("node:crypto");
function verify(rawBody, signature, secret) {
const expected = crypto
.createHmac("sha256", secret)
.update(rawBody)
.digest("hex");
const a = Buffer.from(signature, "utf8");
const b = Buffer.from(expected, "utf8");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Body
| Field | When |
|---|---|
event | Always. order.paid | paid_partial | paid_over | review | expired | cancelled |
event_type | Always. Suffix after order. |
cid | Always. Public payment id from create. |
order_id | Always. Your order id. |
payer_id | If sent on create. |
order_amount | Always. Decimal string. |
order_currency | Always. |
status | Always. Current order status. |
crypto_amount | After a quote is locked. On a payout, the requested crypto amount. |
source_deduction | Order events, once funds are applied. Quote minus received crypto. Informational. |
asset_symbol | After a quote is locked. |
network_name | After a quote is locked. |
payment_address | After a quote is locked. |
txid | When a transfer matched. |
received_amount | When a transfer matched. |
demo | Always. True for events from a demo key: simulated, never credit or debit a customer. |
payout_id | Payout events. Your payout id from create. |
id | Payout events. Bytix payout id. |
amount | Payout events. USD decimal string. |
asset | Payout events. Ticker sent on-chain. |
network | Payout events. Network display name. |
address | Payout events. Destination address. |
fee_amount | Payout events. Fees of the withdrawal, in the payout asset. |
fee_paid_by | Payout events. merchant: the fees come from your balance and the full amount is sent. customer: they are taken off what is sent. |
net_amount | Payout events. Crypto sent on-chain: crypto_amount when you pay the fees, crypto_amount minus fee_amount when the customer does. |
Payout events carry the same fields as Query Payout except quote_rate and created_at. Full field lists: Payment notification and Payout notification.
Retry
If your endpoint errors or does not reply success, we try again automatically: up to six attempts in total, about 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours after the previous one. After the last attempt the delivery is marked failed and shown under Settings → Notifications, where Retry sends the same payload again at once with a fresh signature. Fix your ack first or the retry will fail too.