Webhook Events

Overview

InventPay sends webhook notifications for various events throughout the payment and withdrawal lifecycle. This page documents all available webhook events and their payload structures.

Event Categories

Payment Events

6 events covering the complete payment lifecycle

Withdrawal Events

4 events for withdrawal status changes

Account Events

Coming soon: Balance alerts, API key changes

System Events

Test events and system notifications

Payment Events

payment.created

Sent immediately when a new payment or invoice is created. When to expect:

Right after calling /v1/create_payment or /v1/create_invoice
Within 1-2 seconds of creation

Use cases:

Log payment requests in your system
Send payment link to customer via email/SMS
Track payment funnel analytics
Reserve inventory

Payload:

{
  "event": "payment.created",
  "data": {
    "paymentId": "cmh123abc456def",
    "orderId": "order-12345",
    "amount": 29.99,
    "baseAmount": 29.99,
    "baseCurrency": "USD",
    "currency": "USDT_BEP20",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "invoiceUrl": "https://inventpay.io/invoice/cmh123abc456def",
    "qrCode": "usdt_bep20:0x742d35Cc...?amount=29.99",
    "description": "Premium Plan Subscription",
    "status": "PENDING",
    "expiresAt": "2024-01-01T12:30:00.000Z",
    "createdAt": "2024-01-01T12:00:00.000Z"
  },
  "timestamp": "2024-01-01T12:00:00.500Z",
  "test": false
}

Full Field Descriptions

paymentId

string

Unique payment identifier

orderId

string

Your custom order ID (if provided)

amount

number

Payment amount in cryptocurrency

baseAmount

number

Original amount in base currency

baseCurrency

string

Base currency (USD, USDT, etc.)

currency

string

Cryptocurrency for payment

address

string

Unique payment address

invoiceUrl

string

Hosted payment page URL

status

string

Always “PENDING” for created events

payment.pending

Sent when payment funds are detected on the blockchain but awaiting confirmations. When to expect:

When customer sends cryptocurrency
Before required confirmations are reached
Within seconds of transaction broadcast

Use cases:

Show “Payment detected” message to customer
Update order status to “processing”
Display confirmation progress
Reduce fraud risk assessment

Payload:

{
  "event": "payment.pending",
  "data": {
    "paymentId": "cmh123abc456def",
    "orderId": "order-12345",
    "amount": 29.99,
    "currency": "USDT_BEP20",
    "currentBalance": "29.99",
    "confirmations": 5,
    "requiredConfirmations": 15,
    "status": "PENDING",
    "transactionHash": "0x1234567890abcdef...",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
  },
  "timestamp": "2024-01-01T12:10:00.000Z",
  "test": false
}

Full Field Descriptions

currentBalance

string

Amount received so far

confirmations

number

Current confirmation count

requiredConfirmations

number

Confirmations needed for completion

transactionHash

string

Blockchain transaction hash

payment.confirmed / payment.completed

Sent when payment receives required blockchain confirmations and is complete. When to expect:

After required confirmations (3-15 blocks)
BTC: ~30 minutes
ETH/USDT_ERC20: ~3 minutes
USDT_BEP20: ~45 seconds

Use cases:

Fulfill the order (most important)
Send confirmation email to customer
Update inventory
Issue invoice/receipt
Trigger affiliate commissions
Update accounting systems

Payload:

{
  "event": "payment.confirmed",
  "data": {
    "paymentId": "cmh123abc456def",
    "orderId": "order-12345",
    "amount": 29.99,
    "currency": "USDT_BEP20",
    "currentBalance": "29.99",
    "settlementAmount": 29.85,
    "feeAmount": 0.15,
    "feeRate": 0.005,
    "confirmations": 15,
    "status": "COMPLETED",
    "transactionHash": "0x1234567890abcdef...",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "completedAt": "2024-01-01T12:15:00.000Z"
  },
  "timestamp": "2024-01-01T12:15:00.500Z",
  "test": false
}

Full Field Descriptions

settlementAmount

number

Amount credited to your balance (after fees)

feeAmount

number

Platform fee charged (in cryptocurrency)

feeRate

number

Fee percentage (0.005 = 0.5%)

completedAt

string

Completion timestamp (ISO 8601)

This is the critical event for order fulfillment. Always wait for this event before delivering goods or services.

payment.underpaid

Sent when customer sends less than the required amount (below 95% of required). When to expect:

When received amount < 95% of required
Immediately after detection

Use cases:

Notify customer of shortfall
Display remaining amount needed
Send reminder with payment details
Offer refund option
Update order to “partially paid” status

Payload:

{
  "event": "payment.underpaid",
  "data": {
    "paymentId": "cmh123abc456def",
    "orderId": "order-12345",
    "requiredAmount": "29.99",
    "currentBalance": "25.00",
    "remainingAmount": "4.99",
    "paidPercentage": 83.36,
    "remainingPercentage": 16.64,
    "currency": "USDT_BEP20",
    "status": "PENDING",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "expiresAt": "2024-01-01T12:30:00.000Z"
  },
  "timestamp": "2024-01-01T12:12:00.000Z",
  "test": false
}

Full Field Descriptions

requiredAmount

string

Total amount needed

remainingAmount

string

Still needed to complete payment

paidPercentage

number

Percentage of required amount received

remainingPercentage

number

Percentage still needed

Customers can send additional funds to the same address to complete the payment before expiration.

payment.expired

Sent when payment expiration time is reached without receiving the full amount. When to expect:

At payment expiration time
Default: 30-60 minutes after creation

Use cases:

Cancel the order
Release reserved inventory
Send expiration notification to customer
Offer to create new payment
Log abandoned cart for analytics

Payload:

{
  "event": "payment.expired",
  "data": {
    "paymentId": "cmh123abc456def",
    "orderId": "order-12345",
    "amount": 29.99,
    "currency": "USDT_BEP20",
    "currentBalance": "0",
    "wasUnderpaid": false,
    "status": "EXPIRED",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "expiresAt": "2024-01-01T12:30:00.000Z",
    "createdAt": "2024-01-01T12:00:00.000Z"
  },
  "timestamp": "2024-01-01T12:30:00.500Z",
  "test": false
}

Full Field Descriptions

wasUnderpaid

boolean

True if partial payment was received

currentBalance

string

Final balance at expiration

If wasUnderpaid is true and currentBalance > 0, contact support to discuss refund or manual completion options.

payment.failed

Sent when payment encounters a critical error. When to expect:

Rare: Only during system errors or blockchain issues
Immediately when error detected

Use cases:

Log error for investigation
Notify customer of issue
Create new payment if needed
Alert technical team

Payload:

{
  "event": "payment.failed",
  "data": {
    "paymentId": "cmh123abc456def",
    "orderId": "order-12345",
    "amount": 29.99,
    "currency": "USDT_BEP20",
    "status": "FAILED",
    "error": "Blockchain network error",
    "failureReason": "Unable to monitor address due to network issues",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
  },
  "timestamp": "2024-01-01T12:05:00.000Z",
  "test": false
}

Full Field Descriptions

error

string

Brief error description

failureReason

string

Detailed failure reason

Withdrawal Events

withdrawal.created

Sent when a new withdrawal request is created. Payload:

{
  "event": "withdrawal.created",
  "data": {
    "withdrawalId": "cmh789ghi012jkl",
    "amount": "100",
    "currency": "USDT_BEP20",
    "destinationAddress": "0x1E3D6848dE165e64052f0F2A3dA8823A27CAc22D",
    "status": "PENDING",
    "feeAmount": "0.60",
    "netAmount": 100.0,
    "serviceFee": 0.5,
    "networkFee": 0.1,
    "createdAt": "2024-01-01T13:00:00.000Z",
    "description": "Monthly payout"
  },
  "timestamp": "2024-01-01T13:00:00.500Z",
  "test": false
}

withdrawal.processing

Sent when withdrawal transaction is submitted to the blockchain. Payload:

{
  "event": "withdrawal.processing",
  "data": {
    "withdrawalId": "cmh789ghi012jkl",
    "amount": "100",
    "currency": "USDT_BEP20",
    "destinationAddress": "0x1E3D6848dE165e64052f0F2A3dA8823A27CAc22D",
    "status": "PROCESSING",
    "transactionHash": "0xabcdef1234567890...",
    "confirmations": 2,
    "processedAt": "2024-01-01T13:05:00.000Z"
  },
  "timestamp": "2024-01-01T13:05:00.500Z",
  "test": false
}

withdrawal.completed

Sent when withdrawal is confirmed on the blockchain. Payload:

{
  "event": "withdrawal.completed",
  "data": {
    "withdrawalId": "cmh789ghi012jkl",
    "amount": "100",
    "currency": "USDT_BEP20",
    "destinationAddress": "0x1E3D6848dE165e64052f0F2A3dA8823A27CAc22D",
    "status": "COMPLETED",
    "transactionHash": "0xabcdef1234567890...",
    "confirmations": 15,
    "netAmount": 100.0,
    "completedAt": "2024-01-01T13:15:00.000Z"
  },
  "timestamp": "2024-01-01T13:15:00.500Z",
  "test": false
}

withdrawal.failed

Sent when withdrawal fails (funds returned to balance). Payload:

{
  "event": "withdrawal.failed",
  "data": {
    "withdrawalId": "cmh789ghi012jkl",
    "amount": "100",
    "currency": "USDT_BEP20",
    "destinationAddress": "0x1E3D6848dE165e64052f0F2A3dA8823A27CAc22D",
    "status": "FAILED",
    "failureReason": "Insufficient network funds for gas",
    "fundsReturned": true,
    "createdAt": "2024-01-01T13:00:00.000Z"
  },
  "timestamp": "2024-01-01T13:10:00.000Z",
  "test": false
}

System Events

payment.test

Test webhook event for verifying your endpoint. Payload:

{
  "event": "payment.test",
  "data": {
    "test": true,
    "message": "This is a test webhook from InventPay",
    "timestamp": "2024-01-01T14:00:00.000Z"
  },
  "timestamp": "2024-01-01T14:00:00.500Z",
  "test": true
}

Common Fields

All webhook events include these common fields:

Field	Type	Description
`event`	string	Event type (e.g., “payment.confirmed”)
`data`	object	Event-specific data
`timestamp`	string	When webhook was sent (ISO 8601)
`test`	boolean	True if test event, false for production

Event Headers

All webhook requests include these headers:

Header	Description	Example
`X-Webhook-Signature`	HMAC-SHA256 signature	`a1b2c3d4e5f6...`
`X-Webhook-Event`	Event type	`payment.confirmed`
`X-Webhook-ID`	Unique delivery ID	`wh_123abc456def`
`X-Webhook-Timestamp`	Delivery timestamp	`2024-01-01T12:00:00Z`
`Content-Type`	Always application/json	`application/json`

Event Handling Examples

Basic Event Router

async function handleWebhookEvent(event) {
  const { event: eventType, data } = event;

  switch (eventType) {
    case "payment.created":
      await sendPaymentLinkToCustomer(data);
      break;

    case "payment.confirmed":
      await fulfillOrder(data);
      await sendConfirmationEmail(data);
      break;

    case "payment.underpaid":
      await notifyCustomerOfShortfall(data);
      break;

    case "payment.expired":
      await cancelOrder(data);
      break;

    case "payment.failed":
      await logError(data);
      break;

    case "withdrawal.completed":
      await updateAccountingSystem(data);
      break;

    default:
      console.log("Unhandled event:", eventType);
  }
}

Best Practices

Handle All Relevant Events

Implement handlers for all events relevant to your business logic

Use payment.confirmed for Fulfillment

Only fulfill orders after receiving payment.confirmed event

Log All Events

Keep audit trail of all webhook deliveries

Handle Failures Gracefully

Have contingency plans for failed payments

Test All Event Types

Ensure your code handles all event types correctly

Next Steps

Setup Guide

Configure webhooks in your application

Security

Learn webhook security best practices

Code Examples

See complete webhook implementations

Overview

Back to webhooks overview

Getting Started

Core Concepts

Webhooks

Overview

Event Categories

Payment Events

Withdrawal Events

Account Events

System Events

Payment Events

payment.created

payment.pending

payment.confirmed / payment.completed

payment.underpaid

payment.expired

payment.failed

Withdrawal Events

withdrawal.created

withdrawal.processing

withdrawal.completed

withdrawal.failed

System Events

payment.test

Common Fields

Event Headers

Event Handling Examples

Basic Event Router

Best Practices

Next Steps

Setup Guide

Security

Code Examples

Overview

Getting Started

Core Concepts

Webhooks

​Overview

​Event Categories

Payment Events

Withdrawal Events

Account Events

System Events

​Payment Events

​payment.created

​payment.pending

​payment.confirmed / payment.completed

​payment.underpaid

​payment.expired

​payment.failed

​Withdrawal Events

​withdrawal.created

​withdrawal.processing

​withdrawal.completed

​withdrawal.failed

​System Events

​payment.test

​Common Fields

​Event Headers

​Event Handling Examples

​Basic Event Router

​Best Practices

​Next Steps

Setup Guide

Security

Code Examples

Overview

Overview

Event Categories

Payment Events

payment.created

payment.pending

payment.confirmed / payment.completed

payment.underpaid

payment.expired

payment.failed

Withdrawal Events

withdrawal.created

withdrawal.processing

withdrawal.completed

withdrawal.failed

System Events

payment.test

Common Fields

Event Headers

Event Handling Examples

Basic Event Router

Best Practices

Next Steps