Webhooks

Signed event delivery for transaction state changes. Subscribe, verify, and process events.

OuiPay pushes events to your HTTPS endpoints as transactions change state. You never need to poll for outcomes.

How webhooks work

sequenceDiagram
    participant App as Your Server
    participant API as OuiPay API
    participant Provider as Payment Provider

    App->>API: POST /v1/payments
    API-->>App: 201 (pending)
    Provider-->>API: Payment confirmed
    API->>App: POST /webhooks (signed)
    App-->>API: 200 OK

Subscriptions

curl https://api.ouipay.com/v1/webhooks/subscriptions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/ouipay",
    "events": ["payment.completed", "transfer.completed", "transfer.failed"]
  }'

The subscription object

{
  "id": "01M2S18...",
  "url": "https://yourapp.com/webhooks/ouipay",
  "events": ["payment.completed", "transfer.completed", "transfer.failed"],
  "status": "active",
  "consecutive_failures": 0,
  "created_at": "2026-09-18T02:00:00Z"
}

The signing secret is returned once at creation. Store it in your secrets manager. It cannot be retrieved again; rotate if lost.

The delivery payload

{
  "id": "01M2S18...",
  "event_type": "payment.completed",
  "event_key": "payment.completed:01M2S17G4A0N9MDMXYSCCX8SPS",
  "occurred_at": "2026-09-18T01:13:59Z",
  "data": {
    "transaction_id": "01M2S17G4A0N9MDMXYSCCX8SPS",
    "status": "completed",
    "amount_minor": 101000,
    "currency": "NGN"
  }
}

event_key: unique per event; dedupe on this, not id
data: the canonical transaction payload at event time

Signature headers

Header	Value
`X-OuiPay-Signature`	`sha256=<hex>` HMAC of `ts.body`
`X-OuiPay-Timestamp`	Unix seconds: reject >5 min old

See Verification for implementation details.

Endpoints

Method	Path	Description
POST	`/v1/webhooks/subscriptions`	Create a subscription
GET	`/v1/webhooks/subscriptions`	List subscriptions
GET	`/v1/webhooks/deliveries`	List deliveries
POST	`/v1/webhooks/deliveries/{id}/redeliver`	Requeue a delivery