Webhooks

Receive real-time notifications when events happen in your OpenPay instance. Events are delivered via NATS JetStream and follow the CloudEvents v1.0 specification.

Event Format

Every event is wrapped in a CloudEvents envelope:

JSON

{
  "specversion": "1.0",
  "id": "evt_abc123",
  "source": "urn:core-financial:payment-system",
  "type": "payments.charge.completed",
  "time": "2025-01-15T10:30:00Z",
  "datacontenttype": "application/json",
  "data": {
    "paymentId": "pay_xyz789",
    "amount": 500000,
    "currency": "NGN",
    "status": "succeeded",
    "reference": "txn_abc123"
  }
}

Event Types

payments.charge.completed

A payment was successfully captured.

payments.charge.failed

A payment attempt failed.

payments.charge.pending

A payment is awaiting completion.

payments.charge.refunded

A payment was fully refunded.

payments.charge.disputed

A payment was disputed by the customer.

payments.refund.completed

A refund was processed successfully.

payments.refund.failed

A refund attempt failed.

dlq.event.failed

An event failed processing after max retries.

NATS JetStream Subjects

NATS subjects

# Stream: PAYMENT_EVENTS
# Subjects:
payments.charge.pending
payments.charge.completed
payments.charge.failed
payments.charge.refunded
payments.charge.disputed
payments.refund.completed
payments.refund.failed

# Stream: DLQ_EVENTS
dlq.event.failed

Retry Policy

Payment Events

Max 3 delivery attempts with 30-second acknowledgment wait. Failed events are moved to the DLQ stream.

Dead Letter Queue

Failed events are retained for 7 days. Events in the DLQ include the original event, error details, and retry count.