Skip to main content
Borderless allows integrators to register webhooks in the system. Webhooks enable external systems to receive notifications or updates about withdrawal and deposit events in your account To consume the webhook, register a callback URL where the Borderless will sends a notification via an HTTP POST method with the corresponding payload, documented below. Note: Currently, you cannot specify which events you would like to receive when registering the webhook. Instead, your system will receive all event notifications, and you will need to implement filtering logic on your end to process only the events relevant to your needs. Currently, Web hooks are delivered for transaction-related events, when Deposit, Withdrawal, Transfer, TransferToExternalWallet, Swap or Approval are executed.
If you’re just getting started, please check out our quick start guide.

​
Webhook registration

Use the Endpoint: POST /v1/notifications/webhooks/settings to register a new webhook to receive notifications. Request Example: 
curl -X POST "https://sandbox-api.borderless.xyz/v1/notifications/webhooks/settings" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
     -d '{  
            "url": "https://myapp.com/hooks"
         }'
Response sample: 
{
  "id": "webhook_123456",
  "url": "https://myapp.com/hooks",
  "enabled": true,
  "createdAt": "2024-11-24T12:34:56.789Z",
  "updatedAt": "2024-11-24T12:34:56.789Z"
}
The response contains: id: A unique identifier for the webhook (e.g., webhook_123456). Use this id to delete or update the webhook when needed url: The URL where webhook notifications will be sent enabled: indicates if message devivery is enabled for specific web hook. true by default. createdAt: The timestamp when the webhook was created. updatedAt: The timestamp when the last time the webhook was updated. **Note: ** When a webhook is sent, a 200 OK response is expected to confirm successful delivery. If the receiving endpoint does not respond with a 200 status or raise an error, the system will automatically attempt to retry the delivery multiple times. If all retry attempts fail, the webhook will be marked as disabled by setting "enabled": false. Once disabled, no further webhook events will be delivered to that endpoint. Web hook could be re-enabled using endpoint below

​
Updating webhook

Use the Endpoint: POST https://sandbox-api.borderless.xyz/v1/notifications/webhooks/settings/${id} to update existing webhook url : Request Example: 
curl -X PATCH "https://sandbox-api.borderless.xyz/v1/notifications/webhooks/settings/${id}" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
     -d '{  
            "url": "https://myapp.com/newUrl"
         }'
Please replace ${id} with webhook id you would like to update the URL. Additionally, you could disable the web hook is needed: Request Example: 
curl -X PATCH "https://sandbox-api.borderless.xyz/v1/notifications/webhooks/settings/${id}" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
     -d '{  
            "url": "https://myapp.com/newUrl",
            "enabled": false
         }'
In case the web hook was disabled by Borderless due to failed previous deliveries, you could re-enable it by updating web hook). In case URL should not be changed, just pass it in url field: Request Example: 
curl -X PATCH "https://sandbox-api.borderless.xyz/v1/notifications/webhooks/settings/${id}" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token" \
     -d '{  
            "url": "https://myapp.com/newUrl"
         }'

​
Get webhook by id

Use the Endpoint: GET /v1/notifications/webhooks/settings/${id} to receive all webhooks registered for your organization. Request Example: 
curl -X GET "https://sandbox-api.borderless.xyz/v1/notifications/webhooks/settings/${id}" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token"
Please replace ${id} with webhook id youʼre interested in.

​
Get all registered webhooks

Use the Endpoint: GET /v1/notifications/webhooks/settings to receive all webhooks registered for your organization. Request Example: 
curl -X GET "https://sandbox-api.borderless.xyz/v1/notifications/webhooks/settings" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token"

​
Webhook deletion

Finally, use the Endpoint: DELETE /v1/notifications/webhooks/settings/${id} to delete the webhook by id. Request Example: 
curl -X DELETE "https://sandbox-api.borderless.xyz/v1/notifications/webhooks/settings/${id}" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-access-token"

​
Signing payload using public and private keys

Borderless supports webhooks payload authenticity verification using private and public key pair at organization level. A private key is generated with RSA-SHA256 when first web hook address is registered in the system. The verification process on the caller side could use the corresponding public key along with the payload to validate the signature. To regenerate private and public key, send a request to this API: 
curl -X POST "https://sandbox-api.borderless.xyz/v1/notifications/webhooks/settings/public-key' \
     -H 'accept: application/json' \
     -H "Authorization: Bearer your-access-token"
This call will generate new private & public keys pair and return public key to the caller. Private key is stored securely in Borderless and is not shared under any circumstances with the client To verify the payload extract the payload and the signature from the webhook message’s x-signature header and use previously stored public key for signature validation. In case you didn’t store public key in your application, it could be retrieved using this API call: 
curl -X GET "https://sandbox-api.borderless.xyz/v1/notifications/webhooks/settings/public-key' \
     -H 'accept: application/json' \
     -H "Authorization: Bearer your-access-token"

​
Supported event types

Following event_types are supported:
  • Transaction_Created
  • Transaction_Updated
  • VirtualAccount_Created
  • VirtualAccount_CreationFailed
  • IdentityComplianceCheck_Updated
  • IdentityComplianceCheck_Completed

​
Supported operation types

Web hooks are triggered when one of operation from the list below is executed in the system:
  • Deposit
  • Withdrawal
  • Transfer
  • TransferToExternalWallet
  • Swap
  • Approval
If you have any questions, please don’t hesitate to reach out to us via email or slack.