Webhooks

Webhooks are automated HTTP POST requests sent from one system to another when specific events occur. In payment processing, webhooks notify your server about payment status changes in real-time.

How Webhooks Work

┌─────────────┐    Event occurs    ┌──────────────┐
│   Payment   │ ───────────────▶  │    Your      │
│   Gateway   │   POST /webhook    │   Server     │
└─────────────┘ ◀─────────────── └──────────────┘
                  200 OK response

An event occurs (e.g., payment confirmed)

Gateway sends HTTP POST to your webhook URL

Your server processes the notification

Your server responds with 200 OK

Common Payment Webhook Events

EventDescription

|-------|-------------|

payment.pendingPayment created, awaiting funds payment.confirmedPayment confirmed on blockchain payment.expiredPayment deadline passed payment.failedPayment processing failed

Webhook Security

Always verify webhook authenticity:

HMAC signatures: Verify the X-Signature header

Timestamp validation: Reject old requests

Idempotency: Handle duplicate deliveries

Example Webhook Payload

{
  "event": "payment.confirmed",
  "timestamp": 1705320600,
  "payment": {
    "id": "pay_abc123",
    "status": "CONFIRMED",
    "amount": 100.00,
    "tx_hash": "a1b2c3..."
  }
}

Best Practices

Return 200 quickly: Process asynchronously if needed

Be idempotent: Same webhook may arrive multiple times

Log everything: Debug issues with complete logs

Handle failures: Gateway will retry on non-2xx responses

Related Terms

API Authentication

HMAC Signature

Crypto Payment Gateway

Learn More

Webhook Security Guide

Webhooks Documentation