Webhooks Documentation

Unblock sends webhooks to facilitate the reconciliation of the information, preventing the need for constant synchronous calls to acknowledge the state of a particular process.

Setup

The webhooks will be set up as part of your onboarding. You will be requested to provide the following information:

• The URL to which webhooks will be sent (For Private Sandbox and Production)
• The secret (Different for each environment) shared only with you and Unblock that will be sent in the Authorization headers to prove the webhooks come from Unblock

Ensuring authenticity

As mentioned in the section above, we request that you provide a webhook secret to verify our webhooks.

To ensure authenticity, you should verify each webhook you receive by comparing the Authorization header with the shared secret.

The headers in the webhook are as presented:

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

NOTE: will be replaced with the shared secret

Data and Types

There are three major types of webhooks that we send:

1. fiatToCrypto - Related to fiatToCrypto transactions
2. cryptoToFiat - Related to cryptoToFiat transactions
3. KYC - Related to an Individual KYC process
4. KYB - Related to a Corporate user KYB process
5. AML - Related to AML screenings
6. unblockBankAccount - Related to unblock bank account aka ledgers

Regardless of the type of webhook, the format of the body will always be exactly like this:

{
	"type": fiatToCrypto | cryptoToFiat | KYC | KYB | AML | unblockBankAccount
	"subType": fiatToCrypto_SUBTYPES | cryptoToFiat_SUBTYPES | KYC_SUBTYPES | KYB_SUBTYPES | AML_SUBTYPES | unblockBankAccount_SUBTYPES
	"uuid": uuid // The user's or corporate universal unique identifier
	"data": object // A well-defined object containing additional information for that particular webhook
}

Moving money on chain Webhooks

For these webhooks, the type you will receive in the body is fiatToCrypto.

The uuid field will contain the user's unique identifier.

There are then five possible subtypes that can be assigned in the subtype field:

IN_PROGRESS

This event subType means that we acknowledge receipt of the fiat transfer and are now proceeding with the fiatToCrypto transaction.

CRYPTO_TRANSFER_ISSUED

This event subType means that we have sent the crypto transaction through the network (you will be able to obtain a transaction hash in the data object).

SUCCESS

The crypto transaction has been finalized, and the process has been completed.

ON_HOLD

This is a special state, which can happen for two main reasons:

• The transaction is on hold because the user has not completed KYC and is required to for this transaction to be completed. To identify this situation, you can check the status field inside the data object. If this is the reason the transaction is on hold, the status will be ON_HOLD_KYC. Once the user completes KYC and is approved, the transaction will resume automatically.
• The transaction is on hold due to compliance reasons. This can happen when the original fiat transfer needs further compliance checks due to AML. To identify this situation, you can check the status field inside the data object. If this is the reason for being on hold, the status will be ON_HOLD_PROCESS. Once cleared through AML, it will resume automatically, but you can contact support if you have any questions or concerns.

FAILED

This is also a very special and rare state, which means that the fiatToCrypto transaction failed somewhere along the process. You are advised to contact support if this ever happens.

NOTE: The data object is thoroughly defined below, but if you ever need to contact support over a transaction, you’ll also find the UUID of the transaction in data.transactionUuid. Please provide this uuid whenever possible in such situations to expedite support.

The data object in fiatToCrypto webhooks is defined according to this standard:

{
	"status" : string // Always present, gives more information on the current process status. Particularly useful for on hold events
	"transactionUuid": uuid // Always present, the unique identifier of the fiatToCrypto
	"direction": "fiatToCrypto"
	"amountCrypto": number // Only present on events CRYPTO_TRANSFER_ISSUED and SUCCESS
	"amountFiat": number // Always present
	"walletAddress": string // The address that will receive the crypto
	"transactionHash": string // Only present on events CRYPTO_TRANSFER_ISSUED and SUCCESS
	"currencyFiat": string // Always present, e.g: EUR
	"currencyCrypto": string // Only present on events CRYPTO_TRANSFER_ISSUED and SUCCESS, e.g: usdc
	"fees": number // Only present on events CRYPTO_TRANSFER_ISSUED and SUCCESS
 	"internalBankAccountId": uuid // Unblock account UUID we have received the fiat on
 	"chain": string // Target blockchain that the Crypto will land on
}

NOTE: The value of fees signifies the amount charged by Unblock for the transaction. The currency of that amount if currencyFiat

Moving money off-chain webhooks

For these webhooks, the type you will receive in the body is cryptoToFiat.

The uuid field will contain the user's or corporate unique identifier.

There are then six possible subtypes that can be assigned in the subtype field:

IN_PROGRESS

This event subType means that we acknowledge that we have received the CRYPTO transfer and are now proceeding with the cryptoToFiat transaction

FIAT_TRANSFER_ISSUED

This event subType means that we have sent the fiat transfer

SUCCESS

The fiat transfer has been released or has already been completed, and the process has succeeded

ON_HOLD

This is a special state, which can happen for two main reasons:

• The transaction is on hold because the user has not done KYC and is required to for this transaction. To identify this situation, you can check the status field inside the data object. If this is the reason for being on hold, the status will be ON_HOLD_KYC. Once the user does KYC and is approved, the transaction will resume automatically.
• The transaction is on hold due to compliance reasons. This can happen when the original fiat transfer needs further compliance checks due to AML. To identify this situation, you can check the status field inside the data object. If this is the reason for being on hold, the status will be ON_HOLD_PROCESS. Once cleared through AML, it will resume automatically, but you can contact support if you have further doubts.

FAILED

This is also a very special and rare state, which means that the cryptoToFiat transaction failed somewhere along the process. You are advised to contact support if this ever happens.

LIMIT_BREACHED

This event subType means that the user has tried to start a cryptoToFiat operation but has sent less crypto than what is the lower limit for that particular chain. For example, Ethereum has a lower limit of 10 USDC/T, if the user sends less than that, a notification like this will be produced.

If this notification is ever received, users are advised to either contact support to get the crypto back or they can send an additional sum and the transaction will pick up what was left in the user's wallet.

For instance, if a user sends 5 USDC on Ethereum (the limit is 10) but, after receiving this notification, sends an additional 10 USDC, the transaction will be worth 15 USDC.

In the event of receiving this notification, the data object will have fewer details than normal, because a transaction is never started. You will receive an object like this:

{
  "status": "PROCESS_INITIATION_FAILED",
  "transactionUuid": null, // There is no uuid since the transaction never started
  "amountCrypto": number, // How much crypto was sent
  "chain": string, // The chain in which the crypto was sent
  "currencyCrypto": string, // The token that was sent
  "transactionHash": string, // The transaction hash of the transfer that caused this notification
  "sendingAddress": string, // The address that sent the crypto
  "limit": number // Indicates the limit for this particular chain & token
}

NOTE: The data object will be thoroughly defined now, but if you ever need to contact support over a transaction, you’ll also find the UUID of the transaction in data.transactionUuid. Please provide this uuid whenever possible in those situations.

The data object in cryptoToFiat webhooks is defined according to this standard:

{
	"status" : string // Always present, gives more information on the current process status. Particularly useful for on hold events
	"transactionUuid": uuid // Always present, the unique identifier of the cryptoToFiat
	"direction": "cryptoToFiat" // Always present
	"amountCrypto": number // Always present
	"amountFiat": number // Only present on events FIAT_TRANSFER_ISSUED and SUCCESS
	"transactionHash": string // Always present, the hash of the crypto transaction that triggered the process
	"currencyFiat": string // Only present on events FIAT_TRANSFER_ISSUED and SUCCESS, e.g: EUR
	"currencyCrypto": string // Always present, e.g: usdc
	"fees": number // Only present on events FIAT_TRANSFER_ISSUED and SUCCESS
  "sendingAddress": string // Address onchian that sent us the crypto
	"remoteBankAccountUuid": uuid // Unblock UUID of the remote bank account the fiat is sent to
	"chain": string // Blockchain we have recieved the crypto on
}

NOTE: The value of fees signifies the amount charged by Unblock to the transaction. The currency of that amount iscurrencyCrypto

KYC Webhooks

For these webhooks, the type you will receive in the body is KYC.

The uuid field will contain the user's unique identifier.

There are then two possible subtypes that can be assigned in the subtype field:

• KYC_NEEDED
• PENDING_KYC_DATA
• KYC_PENDING
• SOFT_KYC_FAILED
• HARD_KYC_FAILED

All these statuses are defined here

KYB Webhooks

For these webhooks, the type you will receive in the body is KYB.

The uuid field will contain the corporate's unique identifier.

There are then three possible subtypes that can be assigned in the subType field:

• CREATED
• KYB_PENDING
• ACTIVE

unblockBankAccount Webhooks

For these webhooks, the type will be unblockBankAccount.

The uuid field will contain the client's unique identifier.

There only available subtype at the current moment is statusUpdate.

The ledger status is included within the data object. The structure is as follows:

{ 
  "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 
  } 
}