Developer docs

Webhooks

HTTPS endpoints receive signed JSON events for escrow and payment activity on your account.

Manage endpoints

HTTP

GET  https://www.harrenapay.com/api/public/v1/webhooks
POST https://www.harrenapay.com/api/public/v1/webhooks
DELETE https://www.harrenapay.com/api/public/v1/webhooks/:id

Or use the Merchant dashboard webhooks page (Business plan). See signature verification.

Max 10 endpoints per account. The signing secret is returned once at creation (and on rotation).

Create endpoint

Field	Type	Notes
url	string	HTTPS callback URL (max 2000 chars).
events	string[]	At least one allowed event. Defaults to escrow.funded, escrow.released, escrow.refunded.

cURL

curl -X POST https://www.harrenapay.com/api/public/v1/webhooks \
  -H "Authorization: Bearer hpay_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourstore.com/webhooks/harrenapay",
    "events": ["escrow.funded", "escrow.released", "payment.failed"]
  }'

201 Created

{
  "id": "uuid",
  "url": "https://yourstore.com/webhooks/harrenapay",
  "events": ["escrow.funded", "escrow.released", "payment.failed"],
  "active": true,
  "created_at": "2026-07-17T12:00:00.000Z",
  "secret": "hex…store this securely"
}

List endpoints

200 OK

{
  "endpoints": [
    {
      "id": "uuid",
      "url": "https://yourstore.com/webhooks/harrenapay",
      "events": ["escrow.funded", "escrow.released"],
      "active": true,
      "created_at": "…"
    }
  ]
}

List responses never include secrets.

Events

escrow.funded, escrow.accepted, escrow.declined
escrow.delivered, escrow.released, escrow.refunded
dispute.opened
payment.success, payment.failed — escrow funding credit / failure
charge.success, charge.failed — direct (non-escrow) charge settle

Headers

x-harrenapay-signature — hex HMAC-SHA256 of the raw body
x-harrenapay-event — event name
User-Agent: harrenapay-Webhook/1.0

Payload shape

Events are a flat JSON object (not nested under data). Always look up the escrow/charge by reference on your side.

Example payload

{
  "event": "escrow.funded",
  "reference": "order_4821",
  "amount": 2500000,
  "currency": "NGN"
}

Some events include extra fields (for example dispute_id on dispute.opened). Parse defensively.

Delivery

One automatic retry on network failure or HTTP 5xx. Inspect delivery logs in the Merchant dashboard.

Next: Verify signatures