Webhooks

Retrieve notifications through webhooks on transaction events and status changes

About Our Webhooks 📣

Inabit Terminal uses webhooks to notify your backend when key payment events occur. Webhooks are triggered per widget and can be configured globally at the organization level or overridden per widget.

Terminal supports two webhook types, based on widget type:

• Customer Address Widgets – for persistent payment addresses

• Purchase Address Widgets – for one-time payments

Webhook Events Overview

Widget Type	Event Name	Description
Customer Address	IncomingTransactionReceived	A new transaction is detected (“Unconfirmed” for UTXO blockchains, “Confirming” for non UTXO blockchains)
Customer Address	IncomingTransactionStatusUpdated	Transaction status changes (e.g., “Completed”)
Purchase Address	PurchaseInitiated	Widget is created and ready to receive payment, status=”Initiated”
Purchase Address	PurchaseUpdated	Purchase status or amount has changed

Configuring Webhooks

Organization-Level Webhooks

Webhook URLs are registered during onboarding and apply to all widgets by default. To update these, contact [email protected].

Widget-Level Webhooks

API: When creating a widget, you can override the default webhook URL:

{
  "webhookUrl": "https://yourdomain.com/webhook/inabit"
}

UI: Upon widget creation, you'll be requested to insert a Webhook URL to receive notifications to:

Webhook Event Payloads

IncomingTransactionStatusInitiated

Triggered when a new on-chain transaction is detected for a Customer Address widget.

{
  "event": "IncomingTransactionStatusInitiated",
  "data": {
    "transactionId": "cmd62lqob00yre7014nj501zc",
    "transactionHash": "0xbb22...5011",
    "status": "Pending",
    "amount": 20,
    "sourceAddress": "0x0bf2...",
    "destinationAddress": "0x1973...",
    "asset": "USDT",
    "blockchain": "ethereum-sepolia",
    "customerIdentifier": "[email protected]",
    "widgetId": "31ec71e3-26ed-4653-ad3b-c56f42330510",
    "targetConfirmations": "12"
  }
}

IncomingTransactionReceived

Triggered when a transaction is retrieved/received for the first time. (e.g., Confirming)

{
  "event": "IncomingTransactionReceived",
  "data": {
    "transactionId": "cmdrdvuae01ytec01vtdf3wql",
    "transactionHash": "0x2a754742bce4786b4ca870ab5c15f53e108f56663b949fe570db0db36be3c4ab",
    "status": "Confirming",
    "amount": 5,
    "sourceAddress": "0x2dbcaac27274e0dc7835e0d6c1b3c6bce2712790",
    "destinationAddress": "0xc4870c59e649e1b66d6329e16c6d942cad8e59d4",
    "asset": "USDT",
    "blockchain": "ethereum-sepolia",
    "createdAt": "2025-07-31T12:41:28.093Z",
    "customerIdentifier": "[email protected]",
    "widgetId": "9e37db44-0eea-465e-b35d-907d0a817b89",
    "widgetName": "test 20 customer address",
    "baseCurrency": "USD",
    "baseCurrencyAmount": 4.998749,
    "targetConfirmations": "12"
  }
}

IncomingTransactionStatusUpdated

Triggered when a transaction's status is updated (e.g., Confirmed).

{
  "event": "IncomingTransactionStatusUpdated",
  "data": {
    "transactionId": "cmdrdvuae01ytec01vtdf3wql",
    "transactionHash": "0x2a754742bce4786b4ca870ab5c15f53e108f56663b949fe570db0db36be3c4ab",
    "status": "Completed",
    "amount": 5,
    "sourceAddress": "0x2dbcaac27274e0dc7835e0d6c1b3c6bce2712790",
    "destinationAddress": "0xc4870c59e649e1b66d6329e16c6d942cad8e59d4",
    "asset": "USDT",
    "blockchain": "ethereum-sepolia",
    "createdAt": "2025-07-31T12:41:28.093Z",
    "customerIdentifier": "[email protected]",
    "widgetId": "9e37db44-0eea-465e-b35d-907d0a817b89",
    "widgetName": "test 20 customer address",
    "baseCurrency": "USD",
    "baseCurrencyAmount": 4.998749,
    "targetConfirmations": "12"
  }
}

PurchaseInitiated

Triggered when a Purchase Address widget is created (initiated).

{
  "event": "PurchaseUpdated",
  "data": {
    "purchaseId": "5a7e6bad-8ad8-464f-9892-0f2df100b79c",
    "status": "Initiated",
    "amount": 0,
    "plannedAmount": 0.00000673,
    "asset": "BTC",
    "blockchain": "bitcoin",
    "address": "bc1q8pe73z...",
    "fiatCurrency": "USD",
    "fiatAmount": 0.8,
    "confirmationAmount": 6,
    "widgetId": "bd6510a0-ad66-4f95-ad50-1bc415bf97a6",
    "widgetName": "product widget purchase",
    "purchaseIdentifier": "[email protected]",
    "title": "Payment",
    "subTitle": "The payment description",
    "siteName": "Merchant Site",
    "transactions": [],
    "currentDate": "2025-07-16T11:50:12.835Z",
    "expirationDate": "2025-07-16T12:35:12.388Z",
    "acceptPartialPayment": true,
    "redirectUrl": "http://www.inabit.com"
  }
}

PurchaseUpdated

Triggered when a purchase is updated (payment received, amount confirmed, status changed).

{
  "event": "PurchaseUpdated",
  "data": {
    "purchaseId": "5a7e6bad-8ad8-464f-9892-0f2df100b79c",
    "status": "Completed",
    "amount": 0.000007,
    "plannedAmount": 0.00000673,
    "asset": "BTC",
    "blockchain": "bitcoin",
    "address": "bc1q8pe73z...",
    "fiatCurrency": "USD",
    "fiatAmount": 0.8,
    "confirmationAmount": 6,
    "widgetId": "bd6510a0-ad66-4f95-ad50-1bc415bf97a6",
    "transactions": [
      "e30e54115a76d52b2f857e1f0fa6888c76f2f04edc6095498107eebdf299dff9"
    ],
    "allocationDate": "2025-07-16T11:50:12.388Z",
    "expirationDate": "2025-07-16T12:35:12.388Z",
    "acceptPartialPayment": true,
    "redirectUrl": "http://www.inabit.com"
  }
}

Security and Reliability

Retries

If a webhook delivery fails (e.g., due to a timeout or non-2xx response), Inabit Terminal will wait 30 seconds, then automatically retry the webhook up to 5 additional times, with 30 seconds between each retry

Signature Validation (coming soon): HMAC-based signature header for payload verification.

Best Practices

• Acknowledge webhook events with HTTP 200 OK

• Validate the event type before handling the payload

• Store widgetId or purchaseId to associate the event with your system

• Log all webhook payloads for auditability and replay if needed