{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/legacy-api/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Before you begin","description":"Official Banxa API documentation – on-ramp and off-ramp transfers with identity verification and compliance.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You may receive webhooks when certain order statuses are reached. This is an optional configuration that can reduce the number of API requests you need to send to Banxa."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-begin","__idx":0},"children":["Before you begin"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Log into ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://dashboard.banxa.com/"},"children":["Banxa Dashboard"]}," and configure your webhook URL's which Banxa will use to send your webhooks. You will be able to configure separate webhook URLs for both Sandbox and Production environments."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Otherwise feel free to contact your Account Manager with your Webhook URLs."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"using-webhooks","__idx":1},"children":["Using Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After we have configured your webhook URLs, webhooks will be sent to this URL when an order has changed status. A webhook notification will be sent via ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTP POST"]}," in the below format."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Transition to Webhooks v2 from March 1st:"]}," From March 1st, we will be transitioning from a Legacy Webhook System to it's newer version 2."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"webhook-v2","__idx":2},"children":["Webhook v2"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"order_id\": \"d9efc5d228cb7edfc4b6bb82f7b39f94\",\n  \"status\": \"complete\",\n  \"status_date\": \"2026-01-1604:04:21\",\n  \"created_at\": \"2026-01-1604:04:20\",\n  \"updated_at\": \"2026-01-1604:04:20\",\n  \"external_id\": null,\n  \"order_type\": \"BUY\",\n  \"crypto_coin\": \"USDT\",\n  \"crypto_blockchain\": \"ETH\",\n  \"crypto_amount\": \"67.1000000000000000\",\n  \"fiat_currency\": \"AUD\",\n  \"fiat_amount\": \"100\",\n  \"asset_price\": \"1.490312965722801\",\n  \"payment_method\": \"payid-bank-transfer\",\n  \"processing_fee\": \"0\",\n  \"network_fee\": \"0\",\n  \"usd_exchange_rate\": \"1.4923330\",\n  \"transaction_hash\": \"0\",\n  \"metadata\": []\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"legacy-system","__idx":3},"children":["Legacy System"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{'order_id':'3526ccb0e20f31de92hec732c37bb683'}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you receive a webhook, you can call the Get Order endpoint in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/legacy-api/openapi"},"children":["API Reference"]}," to retrieve detailed order information. This ensures that you do not act on calls from bad actors with incorrect information."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"securing-webhooks","__idx":4},"children":["Securing Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Banxa signs every webhook it sends using HMAC-SHA256. You verify this signature to confirm the request genuinely came from Banxa."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Webhook verification is the reverse of request signing."]}," When you sign outbound API requests to Banxa, you use a Banxa API path in the canonical string. When you verify an incoming webhook, you use the URI path of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["your own webhook endpoint"]}," — for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/webhooks/banxa"]}," — not a Banxa API path. Everything else follows the same algorithm described in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/legacy-api/docs/on-ramp-off-ramp/on-ramp-api-tutorial/step-3-authentication"},"children":["Step 3: Authentication"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each webhook arrives with an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Authorization: Bearer {API Key}:{Signature}:{Nonce}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To verify:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Extract and parse the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header — split on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":"]}," to get the key, signature, and nonce"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Construct the canonical string using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["your webhook endpoint path"]},", the nonce, and the JSON payload"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Compute HMAC-SHA256 of that string using your API secret"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Compare the result to the received signature using a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["timing-safe comparison"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," Use a timing-safe comparison function (not ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["=="]},") to prevent timing-based attacks."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webhook-events","__idx":5},"children":["Webhook Events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A webhook will be triggered and sent to your URL on all Order status transitions. The full list of order statuses can be found ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/legacy-api/docs/resources/order-status"},"children":["here"]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Please note that if you are testing Webhooks in sandbox, you will only receive them when an order has transitioned to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EXPIRED"]},", as orders in our sandbox environment are not live orders where the cryptocurrency can be transferred to the user."]}]}]},"headings":[{"value":"Before you begin","id":"before-you-begin","depth":2},{"value":"Using Webhooks","id":"using-webhooks","depth":2},{"value":"Webhook v2","id":"webhook-v2","depth":3},{"value":"Legacy System","id":"legacy-system","depth":3},{"value":"Securing Webhooks","id":"securing-webhooks","depth":2},{"value":"Webhook Events","id":"webhook-events","depth":2}],"frontmatter":{"title":"Webhooks","seo":{"title":"Before you begin"}},"lastModified":"2026-05-19T23:30:38.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/legacy-api/docs/on-ramp-off-ramp/webhooks","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}