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

Webhook configuration is part of the initial onboarding process. To start receiving webhooks, you'll need to provide the following information to the Unblock team:

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 unique secret key shared between you and Unblock. This secret is used to verify the authenticity of incoming webhooks and ensure they are genuinely sent by Unblock. A different secret will be configured for each environment (Sandbox and Production).

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.

Upon setup, you will receive a unique Webhook Secret. This secret is included 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:

Extract the value from the Authorization header of the incoming webhook request.
Compare this value with the Webhook Secret that was provided to you by Unblock during onboarding 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.

🗂️ 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
- 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.

subType values:

`subType`	Description
`IN_PROGRESS`	Unblock acknowledges receipt of fiat and is processing the fiat-to-crypto transaction.
`CRYPTO_TRANSFER_ISSUED`	Crypto transaction has been sent to the network. `data` object will include `transactionHash` and `amountCrypto`.
`SUCCESS`	Crypto transaction is finalized and process completed.
`ON_HOLD`	Transaction is temporarily paused. Check `data.status` for the reason (e.g., `ON_HOLD_KYC` for KYC requirement, `ON_HOLD_PROCESS` for AML). Once cleared, the transaction will resume automatically.
`FAILED`	Fiat-to-crypto transaction failed. Contact support for assistance.

data object structure for fiatToCrypto 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
  "walletAddress": "string",     // Crypto wallet address receiving the crypto
  "transactionHash": "string",   // Present on `CRYPTO_TRANSFER_ISSUED` and `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")
}

2. `cryptoToFiat` Webhooks

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

subType values:

`subType`	Description
`IN_PROGRESS`	Unblock acknowledges receipt of crypto and is processing the crypto-to-fiat transaction.
`FIAT_TRANSFER_ISSUED`	Fiat transfer has been initiated. `data` object will include `amountFiat`.
`SUCCESS`	Fiat transfer completed successfully.
`ON_HOLD`	Transaction is temporarily paused. Check `data.status` for the reason (e.g., `ON_HOLD_KYC`, `ON_HOLD_PROCESS`). Once cleared, the transaction will resume automatically.
`FAILED`	Crypto-to-fiat transaction failed. Contact support for assistance.
`LIMIT_BREACHED`	User sent crypto amount below the minimum limit for the chain. `data` object will have details and `limit` value. No transaction is initiated.

data object structure for cryptoToFiat 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
  "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
}

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.

subType values:

`subType`	Description
`KYC_NEEDED`	User needs to complete KYC to proceed with further transactions.
`PENDING_KYC_DATA`	User started KYC but is missing required documents.
`KYC_PENDING`	User has submitted documents, KYC verification is in progress.
`SOFT_KYC_FAILED`	KYC verification failed, user may have a chance to correct data or provide more info.
`HARD_KYC_FAILED`	KYC verification permanently failed, user cannot be served.
`FULL_USER`	KYC verification successful, user is fully verified.

Refer to the KYC guide for detailed status definitions.

4. `unblockBankAccount` Webhooks

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

subType values:

`subType`	Description
`statusUpdate`	Status of an Unblock bank account (ledger) has been updated. Check `data.status`.

data object structure for unblockBankAccount 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"?: "PENDING|ACTIVE|DISABLED|FAILED", // Ledger status
  "error"?: "string"           // Optional: Error message if status is FAILED
}

📝 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.

{ 
  "type": "unblockBankAccount"
  "subType": "statusUpdate"
  "uuid": string //user / company uuid
  "data": {
    "uuid": string // ledger uuid
    "currency": string // EUR | GBP | ... 
    "bank_country": string
    "iban"?: string
    "bic"?: string
    "account_number"?: string
    "sort_code"?: string
    "swift_code"?: string
    "bank_code"?: string
    "bank_name"?: string
    "status"?: PENDING | ACTIVE | DISABLED | FAILED
    "error"?: string 
  } 
}

{ 
  "type": "unblockBankAccount"
  "subType": "statusUpdate"
  "uuid": string //user / company uuid
  "data": {
    "uuid": string // ledger uuid
    "currency": string // EUR | GBP | ... 
    "bank_country": string
    "iban"?: string
    "bic"?: string
    "account_number"?: string
    "sort_code"?: string
    "swift_code"?: string
    "bank_code"?: string
    "bank_name"?: string
    "status"?: PENDING | ACTIVE | DISABLED | FAILED
    "error"?: string 
  } 
}

{ 
  "type": "unblockBankAccount"
  "subType": "statusUpdate"
  "uuid": string //user / company uuid
  "data": {
    "uuid": string // ledger uuid
    "currency": string // EUR | GBP | ... 
    "bank_country": string
    "iban"?: string
    "bic"?: string
    "account_number"?: string
    "sort_code"?: string
    "swift_code"?: string
    "bank_code"?: string
    "bank_name"?: string
    "status"?: PENDING | ACTIVE | DISABLED | FAILED
    "error"?: string 
  } 
}

⚙️ Setup

🔒 Ensuring Authenticity

🗂️ Data and Types

✉️ Webhook Types and Subtypes

1. fiatToCrypto Webhooks

2. cryptoToFiat Webhooks

3. KYC Webhooks

4. unblockBankAccount Webhooks

📝 Summary

1. `fiatToCrypto` Webhooks

2. `cryptoToFiat` Webhooks

3. `KYC` Webhooks

4. `unblockBankAccount` Webhooks