Webhook Events

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)

Category	Event types	Description
Invoice lifecycle	`invoice.created`, `invoice.updated`	Invoice state changes (source of truth for payments).
Payment lifecycle	`invoice_payment.created`, `invoice_payment.updated`	Individual payment attempts and settlement status.
Commerce orders	`commerce.order.created`, `commerce.order.updated`	Order lifecycle updates (includes linked invoice/payment context when applicable).
Test deliveries	`test.ping`	Test 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

Overview

API

Merchant

Tokens

Commerce

Payor

WebSockets

Webhooks

Webhook Events

Overview

Authentication

Request

Response

Event envelope (shared)

Errors

Examples

Event types (overview)

Invoice events

`invoice.created`

`invoice.updated`

Payment events

`invoice_payment.created`

`invoice_payment.updated`

Commerce order events

`commerce.order.created`

`commerce.order.updated`

Test event

`test.ping`

Tips for handlers

​Overview

​Authentication

​Request

​Response

​Event envelope (shared)

​Errors

​Examples

​Event types (overview)

​Invoice events

​invoice.created

​invoice.updated

​Payment events

​invoice_payment.created

​invoice_payment.updated

​Commerce order events

​commerce.order.created

​commerce.order.updated

​Test event

​test.ping

​Tips for handlers

Overview

Authentication

Request

Response

Event envelope (shared)

Errors

Examples

Event types (overview)

Invoice events

`invoice.created`

`invoice.updated`

Payment events

`invoice_payment.created`

`invoice_payment.updated`

Commerce order events

`commerce.order.created`

`commerce.order.updated`

Test event

`test.ping`

Tips for handlers