1. Integration
Partner API
  • Getting Started
    • Introduction
    • Authentication
    • Business Use Cases
  • API References
    • Balances & History
      • Get Balances
      • Get Balance History
    • Crypto Deposits
      • Get Crypto Deposit Details
      • Add Travel Rule
    • Crypto Withdrawals
      • Get Whitelisted Wallets
      • Add Whitelisted Wallet
      • Delete Whitelisted Wallet
      • Create Crypto Withdrawal
      • Get Crypto Withdrawal Details
    • SEPA Deposits
      • Get SEPA Payment Details
      • Get SEPA Deposit Details
    • SEPA Withdrawals
      • Create SEPA Withdrawal
      • Get SEPA Withdrawal Details
    • Currency Exchange
      • Get Rates
      • Create Lock
      • Create Exchange
      • Get Exchange Details
  • Integration
    • Integration Guides
    • Transaction Processing
    • Error Handling
    • Rate Limiting
    • Webhooks
      • Crypto Deposit Webhook
      • Crypto Withdrawal Webhook
      • SEPA Deposit Webhook
      • SEPA Withdrawal Webhook
      • Exchange Webhook
  • Reference
    • Supported Currencies
    • Fees
    • FAQ
    • Changelog
    • Support
  1. Integration

Webhooks

Receive real-time notifications about the status of your transactions. Webhooks let you automate follow-up actions and react immediately to deposits, withdrawals and exchanges, without polling the API.

Supported Events#

A webhook is sent with every status change of a transaction. Open any event page to review its payload.
Crypto Deposit
Status updates of incoming crypto deposits, including WAITING-FOR-TRAVEL-RULE.
SEPA Deposit
Status updates of incoming SEPA transfers to your EUR balance.
Crypto Withdrawal
Status updates of crypto withdrawals created via the API or in the web interface.
SEPA Withdrawal
Status updates of SEPA withdrawals from your EUR balance.
Exchange
Status updates of exchanges between EUR and crypto.

Payload#

Every webhook has the same structure:
{
  "type": "CRYPTO_DEPOSIT_UPDATE",
  "data": {
    "type": "DEPOSIT",
    "externalId": "b1f9ef33-03f8-4ad1-84c2-68eb31a798c6",
    "status": "PENDING"
  }
}
type - the event type, e.g. CRYPTO_DEPOSIT_UPDATE or SEPA_DEPOSIT_UPDATE. The type of each event is shown on its page.
data - the transaction in its current status. It has the same fields as the response of the details endpoint of the transaction (e.g. Get Crypto Deposit Details).

Processing Webhooks#

One transaction, several webhooks - each status change sends a new webhook. Use the status in data to determine the current state.
Identify the transaction by externalId - it is present in every webhook. For transactions created via the API, transactionId is included as well.
Handle duplicates and order - the same notification may be delivered more than once, and notifications may arrive out of order. Process webhooks idempotently and ignore a notification if its updatedAt is older than the last one you processed for the transaction.
Use the API as a fallback - if you miss a webhook, check the current status with the details endpoint or Get Balance History.

Security and Verification#

Critical Security Notice
Before processing any webhook notification, always verify its authenticity. This is required for a secure and reliable integration.

Authentication Token Verification#

Every webhook request includes a shared secret token in the HTTP headers.
Implementation steps:
1.
Extract the token
2.
Verify it against your secret
3.
Reject invalid requests
Reject requests with missing or invalid tokens.
If needed, add extra replay protection such as timestamp or nonce validation in your own middleware.

Getting Your Secret Token#

Your webhook URL and secret token are configured with Support during integration setup. Store the token securely and never expose it in client-side code.

Delivery and Retry Policy#

Acknowledging Receipt#

Return any 2xx HTTP status code to confirm successful processing.

Automatic Retry Mechanism#

If delivery fails, up to 4 additional attempts are made with increasing delays.
AttemptDelay After Previous FailureStatus
1st-Initial delivery
2nd~8 secondsFirst retry
3rd~16 secondsSecond retry
4th~32 secondsThird retry
5th~64 secondsFinal retry

Retry Behavior#

Failure Condition: Non-2xx responses or timeouts trigger retries.
Exponential Backoff: Delay increases between attempts.
Timeout: Each request times out after 10 seconds.
Final State: After 5 failed attempts in total, the webhook is treated as permanently failed. Use the details endpoints to reconcile missed updates.

Troubleshooting#

ProblemCauseSolution
401 UnauthorizedInvalid tokenVerify your shared secret token
TimeoutsSlow processingReturn 200 immediately and process asynchronously
Missing updatesDelivery failed after all retriesCheck the status with the details endpoint or Get Balance History
Previous
Rate Limiting
Next
Crypto Deposit Webhook
Built with