BxBytix

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.

  1. 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.
  2. Expose an HTTPS endpoint that accepts POST and reads the raw body. The URL must be reachable from the Bytix API.
  3. Paste that URL under Settings → Notifications and save it. This is the default destination for every order and payout.
  4. 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.
  5. 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.
  6. Optional: pass callback_url on 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:

StatusMeaning
deliveredHTTP 2xx and the body was success
failedThe request errored, or the ack was not success. The response snippet is stored.
skippedNo 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

EventWhen
order.paidThe total received is within your underpay and overpay tolerance of the quote, or a review was accepted
order.paid_partialPart of the quote arrived and the timer is still running: the payer can send the rest
order.paid_overAn overpayment past your overpay tolerance was accepted in review
order.reviewStill 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.expiredTimer elapsed while still open
order.cancelledPayer cancelled checkout
payout.awaiting_approvalCustomer withdrawal created; the amount is held until it is approved
payout.pendingApproved (by the merchant, or automatically under your limit); being sent
payout.rejectedMerchant rejected the payout; the held amount returns to the balance
payout.submittedWithdrawal accepted and sent on-chain
payout.completedOn-chain payout confirmed
payout.failedPayout failed; the held amount returns to the balance
webhook.testSend 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
HTTP/1.1 200 OK
Content-Type: text/plain

success

HTTP 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.

js
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

FieldWhen
eventAlways. order.paid | paid_partial | paid_over | review | expired | cancelled
event_typeAlways. Suffix after order.
cidAlways. Public payment id from create.
order_idAlways. Your order id.
payer_idIf sent on create.
order_amountAlways. Decimal string.
order_currencyAlways.
statusAlways. Current order status.
crypto_amountAfter a quote is locked. On a payout, the requested crypto amount.
source_deductionOrder events, once funds are applied. Quote minus received crypto. Informational.
asset_symbolAfter a quote is locked.
network_nameAfter a quote is locked.
payment_addressAfter a quote is locked.
txidWhen a transfer matched.
received_amountWhen a transfer matched.
demoAlways. True for events from a demo key: simulated, never credit or debit a customer.
payout_idPayout events. Your payout id from create.
idPayout events. Bytix payout id.
amountPayout events. USD decimal string.
assetPayout events. Ticker sent on-chain.
networkPayout events. Network display name.
addressPayout events. Destination address.
fee_amountPayout events. Fees of the withdrawal, in the payout asset.
fee_paid_byPayout events. merchant: the fees come from your balance and the full amount is sent. customer: they are taken off what is sent.
net_amountPayout 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.