> ## Documentation Index
> Fetch the complete documentation index at: https://docs.borderless.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Overview

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.

<Note>
  If you're just getting started, please check out our [quick start guide](/docs/quick-start-guide).
</Note>

## Webhook registration

Use the **Endpoint**: POST `/v1/notifications/webhooks/settings` to register a new webhook to receive notifications.

Request Example:

<CodeGroup>
  ```bash bash theme={null}
  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"
           }'
  ```
</CodeGroup>

Response sample:

<CodeGroup>
  ```bash bash theme={null}
  {
    "id": "webhook_123456",
    "url": "https://myapp.com/hooks",
    "enabled": true,
    "createdAt": "2024-11-24T12:34:56.789Z",
    "updatedAt": "2024-11-24T12:34:56.789Z"
  }
  ```
</CodeGroup>

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:

<CodeGroup>
  ```bash bash theme={null}
  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"
           }'
  ```
</CodeGroup>

Please replace `${id}` with webhook id you would like to update the URL. Additionally, you could disable the web hook is needed:

Request Example:

<CodeGroup>
  ```bash bash theme={null}
  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
           }'
  ```
</CodeGroup>

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:

<CodeGroup>
  ```bash bash theme={null}
  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"
           }'
  ```
</CodeGroup>

## Get webhook by id

Use the **Endpoint**: GET `/v1/notifications/webhooks/settings/${id}` to receive all webhooks registered for your organization.

Request Example:

<CodeGroup>
  ```bash bash theme={null}
  curl -X GET "https://sandbox-api.borderless.xyz/v1/notifications/webhooks/settings/${id}" \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer your-access-token"
  ```
</CodeGroup>

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:

<CodeGroup>
  ```bash bash theme={null}
  curl -X GET "https://sandbox-api.borderless.xyz/v1/notifications/webhooks/settings" \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer your-access-token"
  ```
</CodeGroup>

## Webhook deletion

Finally, use the **Endpoint**: DELETE `/v1/notifications/webhooks/settings/${id}` to delete the webhook by id.

Request Example:

<CodeGroup>
  ```bash bash theme={null}
  curl -X DELETE "https://sandbox-api.borderless.xyz/v1/notifications/webhooks/settings/${id}" \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer your-access-token"
  ```
</CodeGroup>

## 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:

<CodeGroup>
  ```bash bash theme={null}
  curl -X POST "https://sandbox-api.borderless.xyz/v1/notifications/webhooks/settings/public-key' \
       -H 'accept: application/json' \
       -H "Authorization: Bearer your-access-token"
  ```
</CodeGroup>

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:

<CodeGroup>
  ```bash bash theme={null}
  curl -X GET "https://sandbox-api.borderless.xyz/v1/notifications/webhooks/settings/public-key' \
       -H 'accept: application/json' \
       -H "Authorization: Bearer your-access-token"
  ```
</CodeGroup>

## 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

<Info>
  If you have any questions, please don't hesitate to reach out to us via [email](mailto:support@borderless.xyz) or slack.
</Info>