Developer docs

Webhooks

Your endpoint gets a signed JSON event every time something happens to your money.

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}
GET    https://www.harrenapay.com/api/public/v1/webhooks/deliveries
POST   https://www.harrenapay.com/api/public/v1/webhooks/deliveries/{id}/replay

Register from the console (Webhooks) or over the API. The signing secret is returned once, on creation and on rotation. Max 10 endpoints per account.

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": ["charge.success", "payout.completed"]
  }'

Events

Collections

  • charge.success — a customer paid. Carries gross_kobo, collection_fee_kobo and net_kobo.
  • charge.failed — the payment did not complete.
  • collection.refunded — the collection was refunded; carries the refund id and amount.
  • payment.success / payment.failed — escrow funding credit or failure.

Transfers

  • payout.completed — the money reached the bank. Carries fee_kobo and total_debited_kobo.
  • payout.failed — the transfer could not be completed; carries failure_reason.

Escrow

  • escrow.funded, escrow.accepted, escrow.declined
  • escrow.delivered, escrow.released, escrow.refunded
  • escrow.release_failed — a release could not be completed

Disputes

  • dispute.opened, dispute.resolved (with the outcome)

Payload

Flat JSON — not nested under data. Always look the transaction up by reference on your side.

JSON
{
  "event": "charge.success",
  "reference": "order_4821",
  "amount": 2500000,
  "currency": "NGN",
  "gross_kobo": 2500000,
  "collection_fee_kobo": 25000,
  "net_kobo": 2475000
}

Verifying the signature

Every delivery carries an HMAC-SHA256 of the raw request body. Compare it in constant time, and never re-serialize the JSON before checking — that changes the bytes and the signature will not match.

  • x-harrenapay-signature — hex HMAC-SHA256 of the raw body
  • x-harrenapay-event — the event name
  • User-Agent: harrenapay-Webhook/1.0
Node
import { createHmac, timingSafeEqual } from "node:crypto";

const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
const got = request.headers.get("x-harrenapay-signature") ?? "";
const ok =
  got.length === expected.length &&
  timingSafeEqual(Buffer.from(got), Buffer.from(expected));
if (!ok) return new Response("bad signature", { status: 401 });

Delivery and retries

One automatic retry on a network failure or HTTP 5xx. Anything that fails twice is recorded in the delivery log, and you can replay it yourself with POST /webhooks/deliveries/{id}/replay. Answer fast (2xx) and do the heavy work in the background — a slow handler looks like a failed delivery.