Receiving webhooks

You can configure the addresses for sending payment receipt notifications on the project settings page

Please note that when sending a webhook, you must return the following response:

{
  "success": true
}

Otherwise, the service will keep retrying to send the webhook. The maximum number of attempts is 30.

Example of a payment receipt webhook

{
  "amount": "2.395", - Payment amount in USD
  "created_at": "2025-03-17T12:57:52.449795Z", - Payment creation time
  "paid_at": "2025-03-17T12:57:19Z",- Payment execution time
  "status": "completed", - Payment status
  "transactions": {
    "amount": "0.02552778", - Payment amount in cryptocurrency
    "amount_usd": "2.395", - Payment amount in USD
    "bc_uniq_key": "0", - Transaction order number, important in BTC-like networks; bc_uniq_key + tx_hash provides uniqueness
    "blockchain": "litecoin", - Blockchain name
    "created_at": "2025-03-17T12:57:52.449795Z",- Payment creation time
    "currency": "LTC", - Cryptocurrency type
    "currency_id": "LTC.Litecoin", - Cryptocurrency identifier
    "tx_hash": "2be41b0cad76bc5699c3da5d5a1d390f9fb4038e5bfe49aec3b675f9dd4515fd", - Transaction hash
    "tx_id": "4bbc91fd-a950-4fd0-83f3-9f1c09a6b54f" - Transaction ID in the merchant system
  },
  "type": "PaymentReceived",  - Webhook type
  "wallet": {
    "id": "9a07b545-f99e-4f51-bf37-a84fcbe4df4d", - Internal user ID
    "store_external_id": "1" - External user ID
  }
}

Idempotency Check When Receiving a Webhook

Idempotency Check When Receiving a Webhook When processing incoming webhooks, idempotency must be ensured to avoid duplicate processing of the same event. To achieve this, use two fields:

tx_hash — the hash of the request content or event;
bc_uniq_key — a unique event identifier provided by the webhook sender.

Before processing the webhook, you must check that the combination of hash and uniq_key has not been processed previously. If such an event is already recorded, it should be ignored as a duplicate.