API Reference
Start typing to search…

Webhook

The /webhook endpoints let you manage everything related to webhooks.

The section provides comprehensive APIs for managing webhook configurations and events. It enables businesses to register, update, and manage webhook URLs for receiving real-time notifications about key events, such as transaction updates and status changes. Additionally, it offers insights into webhook delivery, including sent payloads, response statuses, and retry mechanisms for failed deliveries. With these features, businesses can easily integrate and monitor webhook events, ensuring seamless communication between their systems and Blaaiz’s platform.

By using Blaaiz's webhooks, you can make your applications instantly responsive to real-time events. For every triggered event, a unique data payload is sent to the webhook URL you’ve specified. You can then use this payload to track important data, automate workflows, and enhance the overall experience for your users.

Getting Started with Webhooks

  • Set up dedicated webhook endpoints and the associated URLs on your servers.
  • Ensure that your endpoints can process the payloads sent by Blaaiz and respond with a 2XX status code to confirm successful handling.
  • Deploy your webhook endpoints and verify that they are publicly accessible. Test their availability to ensure they can receive data from Blaaiz.
  • Once your endpoints are ready, register them on Blaaiz to start receiving real-time event notifications.

Sample Webhook Payload

The webhook request your endpoint will receive is a POST request containing a single JSON object in the message body. This object includes all relevant event data that you can process to trigger actions or updates in your application. Ensure that your endpoint is prepared to handle this structured data efficiently and respond appropriately.


{
  "message": "Transaction Completed",
  "transaction_reference": "000017240425120937445702087012",
  "transaction_status": "SUCCESSFUL",
  "transaction_fee": 0.0,
  "transaction_amount_without_fee": 100.0,
  "transaction_amount": 100.0,
  "transaction_currency": "NGN",
  "virtual_bank_account": {
    "id": "2efecb8d-1128-4363-b77b-bdaaf9b91297",
    "account_number": "3020000086",
    "account_name": "Marcel Buckridge",
    "bank_name": "First Bank of Nigeria"
  },
  "source_information": {
    "account_number": "IDOWU MATHEW DAMILOLA",
    "account_name": "0220901228",
    "bank_name": "WEMA BANK"
  },
  "event_id": "9d46a6c8-4b99-45a0-9f68-12ab6f99a1ce",
  "type": "collection"
}

Webhook Retries

When Blaaiz sends a webhook, the initial delivery is made immediately. If your server does not return a 2XX response, the delivery is marked as failed. To maintain data integrity and ensure that you receive critical notifications, Blaaiz will retry the webhook delivery up to 10 times. Each retry is spaced out with an interval of 1-2 minutes between attempts.

This retry mechanism continues until either:

  1. A successful 2XX response is received from your server, confirming that the webhook has been processed.
  2. The maximum number of 10 retries has been reached, after which no further attempts are made.

By implementing this retry system, we help ensure that temporary issues, such as server downtimes, do not cause missed notifications.


Webhook Verification and Security

To ensure the integrity and authenticity of webhook requests sent from Blaaiz, we implement a verification mechanism using a secret key. This verification process helps protect your application from malicious actors by allowing you to confirm that the webhook was sent by Blaaiz.

How We Send Webhooks Each webhook request contains a cryptographic signature, created using the following process:

  1. Timestamp: When the webhook is generated, we capture the current timestamp, which is included in the request headers (x-blaaiz-timestamp). This helps protect against replay attacks.
  2. Payload: The data being sent in the webhook, represented as a JSON object, is encoded and included in the message body.
  3. Secret Key: The secret key is tied to the API key used to make the request.
  4. Signature: The signature is generated by concatenating the timestamp and the JSON-encoded payload. This string is then hashed using the HMAC-SHA256 algorithm, with the business's secret key as the signing key. The resulting signature is included in the request headers (x-blaaiz-signature).

Header

Content-Type: application/json
User-Agent: Blaaiz
x-blaaiz-timestamp: Contains the timestamp of the request.
x-blaaiz-signature: Contains the HMAC-SHA256 signature for request verification.

Verifying Webhook Requests on Your Server
To verify the webhook request's authenticity, your server should:


  1. Extract the timestamp from the x-blaaiz-timestamp header.
  2. Recreate the signature by concatenating the received timestamp and the JSON payload, then hashing it using the HMAC-SHA256 algorithm with your stored secret key.
  3. Compare the generated signature with the signature provided in the x-blaaiz-signature header. If both match, the request is valid and originates from Blaaiz.