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

  • Log into 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.
  • Otherwise feel free to contact your Account Manager with your Webhook URLs.

Using Webhooks

After we have configured your webhook URLs, webhooks will be sent to this URL when an order has changed staus. A webhook notification will be sent via HTTP POST in the below format.

πŸ“˜

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.

Webhook v2

{
  "order_id": "e82c57b2cba367069dfef4f866c7bc87",
  "status": "expired",
  "status_date": "2024-01-31 12:48:36"
}

Legacy System

{'order_id':'3526ccb0e20f31de92hec732c37bb683'}

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

Your webhooks will 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

A webhook will be triggered and sent to your URL on all Order status transitions. 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.