Webhooks Overview

What are Webhooks?

Webhooks are HTTP callbacks that InventPay sends to your server when specific events occur in your account. Instead of constantly polling our API to check for status changes, webhooks push notifications to you in real-time.

Real-time Updates

Instant notifications when events occur

Reduced API Calls

No need to poll for status changes

Automatic Retry

Failed deliveries automatically retried

Secure

HMAC signature verification included

Why Use Webhooks?

Without Webhooks (Polling)

“ `mermaid sequenceDiagram participant Your Server participant InventPay API loop Every 30 seconds Your Server->>InventPay API: Check payment status? InventPay API—>>Your Server: Still pending end Your Server->>InventPay API: Check payment status? InventPay API—>>Your Server: Completed!

**Problems:**
- Wastes API calls
- Delays in detection
- Increased server load
- Poor user experience

### With Webhooks
```mermaid
sequenceDiagram
    participant Customer
    participant InventPay
    participant Your Server

    Customer->>InventPay: Sends payment
    InventPay->>InventPay: Confirms payment
    InventPay->>Your Server: Webhook: Payment completed
    Your Server->>Customer: Order fulfilled

Benefits:

Instant notifications
No wasted API calls
Better user experience
Reduced server load

Available Webhook Events

InventPay sends webhooks for various events throughout the payment lifecycle:

Payment Events

payment.created

Sent when a new payment or invoice is createdUse for:

Logging payment requests
Sending payment link to customer
Tracking conversion funnel

payment.pending

Sent when payment is received but awaiting confirmations Use for: - Notifying customer payment was detected - Updating order status to “processing” - Showing confirmation progress

payment.confirmed

Sent when payment reaches required confirmations Use for: - Fulfilling orders - Sending confirmation emails - Updating inventory - Recording completed transaction

payment.underpaid

Sent when customer sends less than required amount Use for: - Notifying customer of shortfall - Requesting additional payment - Handling partial refunds

payment.expired

Sent when payment window closes without receiving full payment Use for: - Canceling orders - Releasing reserved inventory - Notifying customer

payment.failed

Sent when payment encounters an errorUse for:

Error logging
Customer notification
Creating new payment if needed

Withdrawal Events

withdrawal.created

Sent when withdrawal request is createdUse for:

Logging withdrawal requests
Notifying finance team

withdrawal.processing

Sent when withdrawal is submitted to blockchain Use for: - Tracking transaction hash - Updating internal records

withdrawal.completed

Sent when withdrawal is confirmed on blockchain Use for: - Final confirmation - Reconciliation - Accounting updates

withdrawal.failed

Sent when withdrawal fails (funds returned)Use for:

Error handling
Retry logic
Notification to finance team

Webhook Workflow

Webhook Delivery

Request Format

InventPay sends webhooks as HTTP POST requests with: Headers:

Content-Type: application/json
X-Webhook-Signature: <HMAC-SHA256 signature>
X-Webhook-Event: <event type>
X-Webhook-ID: <unique delivery ID>
X-Webhook-Timestamp: <ISO 8601 timestamp>

Body:

{
  "event": "payment.confirmed",
  "data": {
    "paymentId": "cmh123abc456",
    "orderId": "order-12345",
    "amount": "29.99",
    "currency": "USDT_BEP20",
    "status": "COMPLETED"
  },
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Response Requirements

Your webhook endpoint must:

Respond quickly (within 5 seconds)
Return HTTP 200 for successful receipt
Verify signature before processing
Be idempotent (handle duplicate deliveries)

Your endpoint must return a 200 status code within 5 seconds, or the delivery will be marked as failed and retried.

Retry Logic

If webhook delivery fails, InventPay automatically retries:

Retry Schedule

Attempt	Delay	Total Time
1st retry	1 minute	1 min
2nd retry	5 minutes	6 min
3rd retry	15 minutes	21 min
4th retry	1 hour	1h 21min
5th retry	3 hours	4h 21min
6th retry	6 hours	10h 21min

Retry Conditions

Retries occur when:

Connection timeout
HTTP status code ≠ 200
Network errors
Server errors (5xx)

Retries DON’T occur when:

HTTP 200 returned (even if body indicates error)
Invalid SSL certificate
Too many redirects

After 6 failed attempts, the webhook is marked as failed and delivery stops. You can view failed webhooks in your dashboard.

Security

Signature Verification

Every webhook includes an HMAC-SHA256 signature to verify authenticity:

const crypto = require("crypto");

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(payload))
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Webhook Security

Learn more about securing your webhooks

Testing Webhooks

Test Webhook Delivery

You can test your webhook endpoint:

const testResult = await sdk.testWebhook();
console.log(testResult.message); // "Webhook test successful"

Test Event Payload

Test webhooks send a payment.test event:

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

Always test your webhook endpoint before going live to ensure proper signature verification and event handling.

Monitoring Webhooks

Webhook Dashboard

View webhook activity in your dashboard:

Delivery history (last 30 days)
Success/failure rates
Average response times
Failed deliveries requiring attention

Webhook Statistics API

Get webhook stats programmatically:

const stats = await sdk.getWebhookStats(7); // Last 7 days
console.log(stats.data.summary.successRate); // "98.5%"

View Webhook Stats

Monitor webhook performance in dashboard

Best Practices

Return 200 Immediately

Process webhooks asynchronously and return 200 quickly

app.post('/webhook', (req, res) => {
  // Return 200 immediately
  res.status(200).send('OK');
  
  // Process asynchronously
  processWebhook(req.body).catch(console.error);
});

Verify Signatures

Always verify webhook signatures before processing

const isValid = verifySignature(req.body, req.headers['x-webhook-signature']);
if (!isValid) {
  return res.status(401).send('Invalid signature');
}

Handle Duplicates

Use webhook ID or payment ID to prevent duplicate processing

if (await db.webhookProcessed(webhookId)) {
  return res.status(200).send('Already processed');
}

Log Everything

Log all webhook deliveries for debugging and auditing

logger.info('Webhook received', {
  event: req.body.event,
  paymentId: req.body.data.paymentId,
  webhookId: req.headers['x-webhook-id']
});

Use HTTPS

Only accept webhooks on HTTPS endpoints for security

Common Issues

Webhooks Not Received

Possible causes:

Webhook URL not configured
Firewall blocking requests
Server not responding in time

Solutions:

Verify URL in dashboard
Check firewall rules
Optimize endpoint performance

Signature Verification Fails

Possible causes: - Wrong webhook secret - Body modified by middleware - Incorrect signature calculation Solutions: - Verify secret from dashboard

Use raw body for verification - Check signature algorithm

Duplicate Webhooks

This is normal: Retries may cause duplicatesSolution: Implement idempotency using webhook ID or payment ID

Quick Start

Configure Webhook URL

Set your webhook endpoint URL in the dashboard or via API

Implement Endpoint

Create an HTTP POST endpoint to receive webhooks

Verify Signatures

Implement signature verification for security

Handle Events

Process different event types appropriately

Test

Use test webhook to verify everything works

Next Steps

Setup Guide

Complete webhook setup instructions

Event Reference

All webhook events and payloads

Security Guide

Secure your webhook endpoint

Example Code

See complete webhook examples

Getting Started

Core Concepts

Webhooks

What are Webhooks?

Real-time Updates

Reduced API Calls

Automatic Retry

Secure

Why Use Webhooks?

Without Webhooks (Polling)

Available Webhook Events

Payment Events

Withdrawal Events

Webhook Workflow

Webhook Delivery

Request Format

Response Requirements

Retry Logic

Retry Schedule

Retry Conditions

Security

Signature Verification

Webhook Security

Testing Webhooks

Test Webhook Delivery

Test Event Payload

Monitoring Webhooks

Webhook Dashboard

Webhook Statistics API

View Webhook Stats

Best Practices

Common Issues

Quick Start

Next Steps

Setup Guide

Event Reference

Security Guide

Example Code

Getting Started

Core Concepts

Webhooks

​What are Webhooks?

Real-time Updates

Reduced API Calls

Automatic Retry

Secure

​Why Use Webhooks?

​Without Webhooks (Polling)

​Available Webhook Events

​Payment Events

​Withdrawal Events

​Webhook Workflow

​Webhook Delivery

​Request Format

​Response Requirements

​Retry Logic

​Retry Schedule

​Retry Conditions

​Security

​Signature Verification

Webhook Security

​Testing Webhooks

​Test Webhook Delivery

​Test Event Payload

​Monitoring Webhooks

​Webhook Dashboard

​Webhook Statistics API

View Webhook Stats

​Best Practices

​Common Issues

​Quick Start

​Next Steps

Setup Guide

Event Reference

Security Guide

Example Code

What are Webhooks?

Why Use Webhooks?

Without Webhooks (Polling)

Available Webhook Events

Payment Events

Withdrawal Events

Webhook Workflow

Webhook Delivery

Request Format

Response Requirements

Retry Logic

Retry Schedule

Retry Conditions

Security

Signature Verification

Testing Webhooks

Test Webhook Delivery

Test Event Payload

Monitoring Webhooks

Webhook Dashboard

Webhook Statistics API

Best Practices

Common Issues

Quick Start

Next Steps