Bloquo Webhooks are a critical real-time notification mechanism that ensures clients are immediately informed about any status change in their Deposit or Withdrawal orders.
Unlike a polling system, Bloquo actively sends an HTTP POST request to a URL you specify when creating the order, ensuring instant and efficient communication.
Order Creation: When creating a new Deposit or Withdrawal order via the API, the client must include the target URL in the WebhookUrl property of the request body.
Monitoring: Bloquo monitors the internal status of the order.
Notification: Whenever the order's status changes (e.g., from PENDING to COMPLETED or FAILED), Bloquo sends an HTTP POST request to the provided WebhookUrl.
Confirmation: The client's endpoint MUST respond with an HTTP 200 OK status to confirm that the notification has been received and will be processed.
The POST request sent by Bloquo will contain a detailed JSON body with all the updated order information, including:
| Main Field | Type | Description |
| Status | STRING | The new status of the order (e.g., COMPLETED, FAILED). This is the key field. |
| OrderId | INTEGER | The unique Bloquo order ID. |
| OrderType | STRING | Type of order (Withdrawal or Deposit). |
| E2EId | STRING | End-to-End Identifier (if applicable), useful for tracking. |
| RequestedAmount | DECIMAL | The value originally requested. |
| TotalAmount | DECIMAL | The total value after fees. |
| FeeAmount | DECIMAL | The fee amount charged (if any). |
| FinalizedAt | DATETIME | Timestamp of when the current status was finalized. |
| FailureReason | STRING | The code and description of the failure reason (if Status is FAILED). |
(Refer to the Withdrawal Order and Deposit Order examples for the complete structure.)
Important: Webhook requests DO NOT use a Bearer Token, hash, or security signature in the request.
Communication security is ensured through Source Validation.
All webhook requests come EXCLUSIVELY from Bloquo's API servers.
Servers are segregated by environment (Sandbox, Production, etc.).
Required Action: To validate the source of the request on your endpoint, you MUST request the official origin endpoint or IP address corresponding to your integration environment from Bloquo and configure your firewall/server to accept requests only from this source.
Bloquo uses a robust retry policy to ensure notification delivery, in case your server does not acknowledge receipt.
| Retry Condition | Action |
| Occurrence: | Your server DOES NOT return an HTTP 2xx status (e.g., 200 OK) to Bloquo. |
| Mechanism: | Exponential Backoff with Jitter (Exponential delay with random variation). |
| Base Delay: | 1 minute. |
| Pattern: | The delay doubles with each retry, with a small random variation (approx. 1m β 2m β 4m β 8m...). |
| Maximum: | 10 attempts. |
| Final Result: | After 10 failures, the webhook is permanently marked as Failed, and there will be no further automatic attempts. |
To ensure a reliable and efficient webhook integration, follow these recommendations:
Immediate Response (200 OK): Your endpoint must return HTTP 200 OK as quickly as possible. Heavy logic processing, database updates, or other time-consuming tasks MUST be handled asynchronously (in a queue/background). This prevents timeouts and unnecessary retries from Bloquo.
Idempotency: Make your endpoint idempotent. If Bloquo sends a duplicate notification (which can occur during network failures before the 200 OK receipt), processing the second notification should not cause unwanted side effects (e.g., crediting the customer twice). Use the OrderId and Status to check if the event has already been processed.
Logging: Log (record) all incoming webhook requests in full. This is crucial for auditing, troubleshooting, and validation against the Bloquo system.
Data Validation: Before processing the notification, validate that the OrderId and E2EId values match the data expected in your system.