Webhooks

Unblock API uses webhooks to provide you with real-time, asynchronous updates on the status of various processes. Instead of constantly polling our API for changes, you'll receive push notifications directly to your designated URL whenever key events occur. This is crucial for efficient integration and keeping your systems synchronized with Unblock's platform.

⚙️ Setup

To receive real-time updates from Unblock, you need to configure a webhook.

• Webhook URL: The URL endpoint on your server where Unblock will send webhook notifications. This URL will be configured separately for your Sandbox and Production environments.
• Webhook Secret: A shared secret used to verify webhook authenticity. A different secret will be configured for each environment (Sandbox and Production).

Configuring your webbhook

You can configure or update your webhook settings at any time using the Update merchant details endpoint. Make sure to use the correct API key for each environment. Sandbox and Production must be configured separately.

Learn more about the onboarding process and environment setup.

🔒 Ensuring Authenticity

Security is paramount. To guarantee that webhooks are genuinely from Unblock and not from a malicious third party, you must verify the authenticity of each webhook you receive. This is done by validating the Authorization header in the webhook request.

Unblock will include the Webhook Secret that you provided during setup in the Authorization header of every webhook sent to your Webhook URL.

Webhook Header Example:

{
  "Accept": "application/json",
  "Content-type": "application/json",
  "Authorization": "API-Key <YOUR_WEBHOOK_SECRET>"
}

To verify authenticity:

1. Extract the value from the Authorization header of the incoming webhook request. Compare this value with the Webhook Secret that you configured and provided to Unblock for the corresponding environment. If the values match, the webhook is authentic and originates from Unblock. If they don't match, discard the webhook as it may be fraudulent.

It is crucial to implement this verification step in your webhook handling logic to maintain the security of your integration.

🗂️ Webhook Delivery and Reliability

Unblock is committed to reliably delivering webhook notifications to your configured endpoint. However, network issues or temporary unavailability on your server's side can sometimes prevent immediate delivery.

• Retry Attempts: We will attempt to deliver a webhook up to 5 times in total (the initial attempt + 4 retries).

• Retry Schedule: The delay between retries increases with each attempt, calculated as: n ** 6 + 2 seconds, where n is the attempt number (starting from n=1 for the first retry).

  • After 1st failed attempt (n=1): Retry after 1⁶ + 2 = 3 seconds.
  • After 2nd failed attempt (n=2): Retry after 2⁶ + 2 = 64 + 2 = 66 seconds (approx. 1 minute).
  • After 3rd failed attempt (n=3): Retry after 3⁶ + 2 = 729 + 2 = 731 seconds (approx. 12 minutes).
  • After 4th failed attempt (n=4): Retry after 4⁶ + 2 = 4096 + 2 = 4098 seconds (approx. 1 hour 8 minutes).

It is crucial to ensure your webhook endpoint is robust and acknowledges webhooks promptly to avoid unnecessary retries and potential delays in receiving updates. If all 5 attempts fail, the webhook will not be sent again for that specific event.

🗂️ Data and Types

Unblock webhooks follow a consistent structure, making them easy to parse and process. Regardless of the specific event, the webhook body will always adhere to the following JSON format:

{
  "type": "webhookType",
  "subType": "webhookSubType",
  "uuid": "entityUuid",
  "data": {
    // ... event-specific data ...
  }
}

• type: Indicates the broad category of the webhook event. Possible values include:

  • fiatToCrypto
  • cryptoToFiat
  • KYC
  • KYB
  • unblockBankAccount

• subType: Provides a more granular classification of the event within the type. For example, under fiatToCrypto, subtypes could be IN_PROGRESS, SUCCESS, FAILED, etc.

• uuid: The universal unique identifier of the user or corporate entity associated with the event. This allows you to easily link the webhook to the relevant user in your system.

• data: A JSON object containing detailed information specific to the webhook event. The structure and fields within data will vary depending on the type and subType.

✉️ Webhook Types and Subtypes

Here's a detailed look at each webhook type and their possible subType values:

1. fiatToCrypto Webhooks

Triggered by events in fiat-to-crypto transactions.

subTypevalues:

dataobject structure forfiatToCrypto webhooks:

NOTE: If you ever need to contact support over a transaction, please provide the transactionUuid value.

{
  "status": "string",             // Process status (e.g., "IN_PROGRESS", "ON_HOLD_KYC", "SUCCESS")
  "transactionUuid": "uuid",      // Unique identifier of the fiat-to-crypto transaction
  "direction": "fiatToCrypto",    // Always "fiatToCrypto"
  "amountCrypto": number,         // Present on `CRYPTO_TRANSFER_ISSUED` and `SUCCESS` - Amount of crypto transferred
  "amountFiat": number,           // Always present - Amount of fiat received
  "amountRefunded": number,      // Present only on subtype REFUNDED. The amount that was refunded, in currencyFiat.
  "walletAddress": "string",      // Crypto wallet address receiving the crypto
  "transactionHash": "string",    // Present on `SUCCESS` - Blockchain transaction hash
  "currencyFiat": "string",       // Always present - Fiat currency (e.g., "EUR")
  "currencyCrypto": "string",     // Present on `CRYPTO_TRANSFER_ISSUED` and `SUCCESS` - Crypto currency (e.g., "usdc")
  "fees": number,                 // Present on `CRYPTO_TRANSFER_ISSUED` and `SUCCESS` - Unblock's transaction fees in `currencyFiat`
  "internalBankAccountId": "uuid", // Unblock bank account UUID where fiat was received
  "chain": "string",              // Target blockchain for crypto transfer (e.g., "Ethereum")
  "senderDetails": {              // Returned on fiatToCrypto webhooks
    "senderName": "string",       // The full name of the account holder who sent the fiat.
    "senderCountry": "string",    // ISO 3166-1 alpha-2 code of the sender's bank country.
    "accountDetails": {           // Returned only to certain merchants
      // This object contains the sender's bank details in a structured format.
      // Example for EUR:
      "currency": "EUR",
      "iban": "1234567890"
    }
  } | undefined,
  "sendingWalletAddress": "string" // Crypto address, it can be undefined for open-banking
}

2. cryptoToFiat Webhooks

Triggered by events in crypto-to-fiat transactions (off-ramping). The uuid field will contain the user's unique identifier.

subTypevalues:

dataobject structure forcryptoToFiat webhooks:

NOTE: If you ever need to contact support over a transaction, please provide the transactionUuid value

{
  "status": "string",             // Process status (e.g., "IN_PROGRESS", "ON_HOLD_KYC", "SUCCESS", "PROCESS_INITIATION_FAILED")
  "transactionUuid": "uuid",      // Unique identifier of the crypto-to-fiat transaction (null for `LIMIT_BREACHED`)
  "direction": "cryptoToFiat",    // Always "cryptoToFiat"
  "amountCrypto": number,          // Always present - Amount of crypto received
  "amountFiat": number,            // Present on `FIAT_TRANSFER_ISSUED` and `SUCCESS` - Amount of fiat transferred
  "amountRefunded": number,      // Present only on subtype REFUNDED. The amount that was refunded, in currencyCrypto.
  "transactionHash": "string",     // Always present - Blockchain transaction hash of crypto transfer
  "currencyFiat": "string",        // Present on `FIAT_TRANSFER_ISSUED` and `SUCCESS` - Fiat currency (e.g., "EUR")
  "currencyCrypto": "string",      // Always present - Crypto currency (e.g., "usdc")
  "fees": number,                 // Present on `FIAT_TRANSFER_ISSUED` and `SUCCESS` - Unblock's transaction fees in `currencyCrypto`
  "sendingAddress": "string",      // Blockchain address that sent the crypto
  "remoteBankAccountUuid": "uuid", // Unblock UUID of the destination bank account for fiat
  "chain": "string",               // Blockchain where crypto was received (e.g., "Polygon")
  "limit": number,                // Present on `LIMIT_BREACHED` - Minimum limit for the chain & token
  "beneficiaryDetails": { // Returned on cryptoToFiat webhooks
      "receiverName": "string", // The full name of the beneficiary.
      "accountDetails": {
          // This object contains the destination bank details in a structured format.
          // Example for an NGN beneficiary:
          "currency": "NGN",
          "accountNumber": "1234567890",
          "bankCode": "044",
          "bankName": "Access Bank"
      },
}

3. KYC Webhooks

Triggered by changes in the Know Your Customer (KYC) verification status for individual users. The uuid field will contain the user's unique identifier.

subTypevalues:

Refer to the KYC guide for detailed status definitions.

4. KYB Webhooks

Triggered by changes in the Know Your Business (KYB) verification status for corporates. The uuid field will contain the corporate's unique identifier.

subTypevalues:

5. unblockBankAccount Webhooks

Triggered by updates to the status of Unblock bank accounts (ledgers). The uuid field will contain the user or corporate unique identifier.

subTypevalues:

dataobject structure forunblockBankAccount webhooks:

{
  "uuid": "string",           // Ledger UUID
  "currency": "string",       // Currency of the ledger (e.g., "EUR", "GBP")
  "bank_country": "string",   // Bank country code
  "iban"?: "string",          // Optional: IBAN if applicable
  "bic"?: "string",           // Optional: BIC/SWIFT code if applicable
  "account_number"?: "string", // Optional: Account number if applicable
  "sort_code"?: "string",      // Optional: Sort code if applicable
  "swift_code"?: "string",     // Optional: SWIFT code if applicable
  "bank_code"?: "string",      // Optional: Bank code if applicable
  "bank_name"?: "string",      // Optional: Bank name if applicable
  "status"?: "ACTIVE" | "WAITING_CREATION" | "FAILED_CREATION" | "DISABLED", // Ledger status
  "error"?: "string"           // Optional: Error message if status is FAILED
}

5. linkedBankAccountProfile Webhooks

Triggered by updates to the status of profile creation for linked bank accounts.

subType values:

data object structure for linkedBankAccountProfile webhooks:

{
  "uuid": "string",           // Profile UUID
  "status"?: "ACTIVE|WAITING_CREATION|FAILED_CREATION|DISABLED", // Profile status
  "error"?: "string"           // Optional: Error message if status is FAILED_CREATION
}

6. linkBankAccount Webhooks

Triggered by updates to the status of linking a bank account to profile.

subType values:

data object structure for linkBankAccount webhooks:

{
  "uuid": "string",           // Linked bank account UUID
  "status"?: "CHECK_PENDING|CHECK_COMPLETED|ACTIVE|PENDING|FAILED|DISABLED", // Linked bank account status
  "error"?: "string"           // Optional: Error message if status is FAILED_CREATION
}

📝 Summary

Webhooks are essential for building reactive and efficient integrations with the Unblock API. By correctly setting up your webhook URL, verifying authenticity, and parsing webhook payloads, you can receive real-time updates on transaction statuses, KYC/KYB processes, and other critical events, enabling you to build robust and user-friendly payment experiences. Make sure to carefully handle and process each webhook type and subtype to ensure your application logic correctly responds to different events within the Unblock ecosystem.