Webhooks

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.

Before you begin

• Provide your Account Manager with your Webhook URL which Banxa will use to send your webhooks. You can provide Banxa with a separate webhook URL for your testing and for your production environments.

Using Webhooks

After we have configured your webhook URLs, webhooks will be sent to this URL when an order has transitioned to a particular status. A webhook notification will be sent via HTTP POST in the below format and will only include the Order ID.

{'order_id':'ABCD1234'}

When you receive a webhook, you can then call the Get Order endpoint to retrieve detailed order information. This ensures that you do not receive calls from bad actors with incorrect information.

Securing Webhooks

If required, webhooks can be sent with HMAC authentication. HMAC guarantees that the message is from Banxa and has not been altered on the way by a third party.

Banxa will use the same secret provided to you during onboarding to encrypt the signature. You will receive the webhook with an Authorization Header that is generated and formatted in the same way as your API requests to Banxa i.e. "Authorization: Bearer API Key:Signature:Nonce". In order to decode the encryption, you will need to repeat the hash operation by computing the HMAC with the SHA256 hash function, and then perform an equality match.

When checking the validity of the request, ensure you use the same method to generate the HMAC outlined in Step 3: Authentication

Note. We will use the URI path of the webhook endpoint provided and the payload specified above when generating the signature.

Webhook Events

As webhook will be triggered and sent to your URL when the order has transitioned to the below statuses. The full list of order statuses can be found here

📘

Please note that if you are testing Webhooks in sandbox, you will only receive them when an order has transitioned to EXPIRED, as orders in our sandbox environment are not live orders where the cryptocurrency can be transferred to the user.

📘

The WAITINGPAYMENT status is applicable to Off-Ramp orders only. This status occurs when the customer has completed KYC and submitted their Bank Account details for receiving fiat. This webhook will notify you that cryptocurrency is ready to be sent to Banxa.