Webhook Notifications
This document outlines the necessary information to integrate and handle the supported webhook functionalities for platform events. It documents in detail the types of notifications available, the structure of webhook payloads, and the necessary headers for secure communication between StablR and your platform. The webhooks are essential for real-time updates, allowing seamless and effective integration with external systems.
Configuration
StablR's platform allows customers with Admin role to create a webhook subscription in their StablR Account. This can be achieved by going to the Account > Management > Notifications section.
In order to configure your webhook subscription go to the Account > Management > Notifcations section and then select Add Hook.
Subsequently, provide the following values:
| Field | Description |
|---|---|
| Display Name | A friendly identified for subscription |
| URL | Webhook destination where notification will be posted (HTTPS only) |
| Secret | A custom secret which will be used to sign notifications (HMAC-SHA256) |
And click Create.
Notifications
Wallet
Wallet notifications inform you of the status changes in wallet creation and management.
- PENDING: Wallet has been created and is under review.
- APPROVED: Wallet has passed review and is approved for use.
- REJECTED: Wallet has been rejected and is not eligible for use.
- DELETED: Wallet has been deleted and is no longer in use.
DepositOrder
DepositOrder (also known as Buy Orders) notifications keep you updated on the progress of deposit transactions.
- PENDING: The deposit order has been created and is awaiting further processing.
- CONFIRMED: Fiat funds have been received, and crypto assets have been successfully minted.
- REJECTED: The order has been halted due to incorrect data or mistakes.
WithdrawOrder
WithdrawOrder (also known as Sell Orders) notifications provide real-time updates on the status of withdrawal transactions.
- PENDING: The withdraw order has been created and is awaiting further processing.
- AWAITING_PAYOUT: The customer has transferred crypto assets to the burn wallet address and is waiting for the payout.
- CONFIRMED: Fiat funds have been transferred back to the customer, completing the order.
- REJECTED: The order has been halted due to incorrect data or mistakes.
Webhook structure
The webhook payload contains crucial information about the event. Below the structure of the payload is oultined:
Payload
{
"EntityId": "f3c09c61-e47a-4b5a-826d-74edb6fa98a9",
"Timestamp": "2024-06-07T10:50:02.6286227Z",
"EntityName": "DepositOrder",
"EntityStatus": "PENDING"
}
| Property | Type | Description | Format / Example |
|---|---|---|---|
| EntityId | guid | Unique identifier for the entity | f3c09c61-e47a-4b5a-826d-74edb6fa98a9 |
| Timestamp | date | Event timestamp in UTC | 2024-06-07T10:50:02.6286227Z |
| EntityName | string | Name of the entity (DepositOrder, WithdrawOrder, Wallet) | DepositOrder |
| EntityStatus | string | Current status of the entity | PENDING, AWAITING_PAYOUT, CONFIRMED, REJECTED |
Headers
Headers ensure the security and integrity of the webhook payload. The following headers are included:
| Header | Comment | Example |
|---|---|---|
| x-request-timestamp | UNIX timestamp in milliseconds | 1717757410412 |
| x-content-hash | Base64 representation of payload hash | Yg3K/ehHtiTgGTVJIA/hd333mAT1XTdKo6abpjuJAzc= |
| authorization | Base64 representation of HMAC signature <URL>::<CONTENT_HASH> using client's secret during computation. | HMACSHA256 <HMAC_SHA256_SIGNATURE> |
Security Considerations
To ensure the security of the webhook data:
- Validate the x-request-timestamp: Ensure the timestamp is within an acceptable range to prevent replay attacks.
- Verify the x-content-hash: Compute the hash of the received payload and compare it with the x-content-hash to ensure data integrity.
- Authenticate the authorization header: Recompute the HMAC signature using your secret key and compare it with the received authorization header.