Skip to main content

​
Overview

Use this page to map webhook event types to payload shapes. The same PepayEvent envelope is used by WebSocket event_v1 frames.

​
Authentication

Webhook deliveries are signed. Validate X-Pepay-Timestamp and signature headers before parsing business logic payloads. See Webhook Authentication.

​
Request

Webhook endpoints receive POST requests with JSON payloads: 
curl -X POST "https://merchant.example.com/webhooks/pepay" \
  -H "Content-Type: application/json" \
  -d '{"id":"evt_example","object":"event","type":"test.ping","created":1700000000,"data":{"object":{"object":"ping","status":"ok"}}}'

​
Response

​
Event envelope (shared)

All webhook deliveries use the canonical PepayEvent envelope. WebSocket event_v1 frames use the same shape, so you can reuse handlers across webhooks and WebSockets. 
{
  "id": "evt_1700000000000-123",
  "object": "event",
  "type": "invoice.updated",
  "created": 1700000000,
  "data": {
    "object": {
      "object": "invoice",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "paid"
    }
  }
}
See WebSockets for the realtime stream that mirrors these event types.

​
Errors

  • 400 should be returned for invalid signature or invalid payload.
  • Non-2xx responses trigger retry delivery attempts.
  • Treat handlers as idempotent due at-least-once delivery semantics.

​
Examples

​
Event types (overview)

CategoryEvent typesDescription
Invoice lifecycleinvoice.created, invoice.updatedInvoice state changes (source of truth for payments).
Payment lifecycleinvoice_payment.created, invoice_payment.updatedIndividual payment attempts and settlement status.
Commerce orderscommerce.order.created, commerce.order.updatedOrder lifecycle updates (includes linked invoice/payment context when applicable).
Test deliveriestest.pingTest event sent from the dashboard.

​
Invoice events

​
invoice.created

{
  "id": "evt_1700000001000-456",
  "object": "event",
  "type": "invoice.created",
  "created": 1700000001,
  "data": {
    "object": {
      "object": "invoice",
      "id": "inv_123",
      "status": "unpaid",
      "amount_usd": 49,
      "environment": "devnet"
    }
  }
}

​
invoice.updated

{
  "id": "evt_1700000002000-789",
  "object": "event",
  "type": "invoice.updated",
  "created": 1700000002,
  "data": {
    "object": {
      "object": "invoice",
      "id": "inv_123",
      "status": "paid",
      "paid_at": 1735689600,
      "environment": "mainnet"
    }
  }
}

​
Payment events

​
invoice_payment.created

{
  "id": "evt_1700000003000-111",
  "object": "event",
  "type": "invoice_payment.created",
  "created": 1700000003,
  "data": {
    "object": {
      "object": "invoice_payment",
      "id": "pay_123",
      "invoice_id": "inv_123",
      "status": "pending",
      "settlement_status": "pending",
      "amount_usd": 49,
      "environment": "devnet"
    }
  }
}

​
invoice_payment.updated

{
  "id": "evt_1700000004000-222",
  "object": "event",
  "type": "invoice_payment.updated",
  "created": 1700000004,
  "data": {
    "object": {
      "object": "invoice_payment",
      "id": "pay_123",
      "invoice_id": "inv_123",
      "status": "confirmed",
      "settlement_status": "settled",
      "settlement": {
        "summary_status": "settled",
        "stage": "final",
        "merchant_settlement_id": 30,
        "settlement_tx_hash": "0xabc123",
        "network": "bsc",
        "status": "settled"
      },
      "environment": "mainnet"
    }
  }
}

​
Commerce order events

​
commerce.order.created

{
  "id": "evt_1700000005000-333",
  "object": "event",
  "type": "commerce.order.created",
  "created": 1700000005,
  "data": {
    "object": {
      "object": "commerce_order",
      "id": "order_123",
      "status": "placed",
      "invoice_id": "inv_123",
      "environment": "devnet"
    }
  }
}

​
commerce.order.updated

{
  "id": "evt_1700000006000-444",
  "object": "event",
  "type": "commerce.order.updated",
  "created": 1700000006,
  "data": {
    "object": {
      "object": "commerce_order",
      "id": "order_123",
      "status": "fulfilled",
      "invoice_id": "inv_123",
      "environment": "mainnet"
    }
  }
}

​
Test event

​
test.ping

{
  "id": "evt_1700000007000-555",
  "object": "event",
  "type": "test.ping",
  "created": 1700000007,
  "data": {
    "object": {
      "object": "ping",
      "status": "ok"
    }
  }
}

​
Tips for handlers

  • Treat invoice as the source of truth for payment state.
  • Dedupe by event.id (also sent as X-Pepay-Event-ID).
  • Keep handlers idempotent for at-least-once delivery.
Next: Webhook Authentication