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

IncomingTransactionStatusInitiated

A new transaction is detected (unconfirmed)

Customer Address

IncomingTransactionStatusUpdated

Transaction status changes (e.g., confirmed)

Purchase Address

PurchaseInitiated

Widget is created and ready to receive payment

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

IncomingTransactionStatusUpdated

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

{
  "event": "IncomingTransactionStatusUpdated",
  "data": {
    "transactionId": "cmd62lqob00yre7014nj501zc",
    "transactionHash": "0xbb22...5011",
    "status": "Completed",
    "amount": 20,
    "sourceAddress": "0x0bf2...",
    "destinationAddress": "0x1973...",
    "asset": "USDT",
    "blockchain": "ethereum-sepolia",
    "customerIdentifier": "[email protected]",
    "widgetId": "31ec71e3-26ed-4653-ad3b-c56f42330510",
    "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

Last updated

Was this helpful?