Developer docs
Webhooks
Your endpoint gets a signed JSON event every time something happens to your money.
Endpoints
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}/replayRegister 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 -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. Carriesgross_kobo,collection_fee_koboandnet_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. Carriesfee_koboandtotal_debited_kobo.payout.failed— the transfer could not be completed; carriesfailure_reason.
Escrow
escrow.funded,escrow.accepted,escrow.declinedescrow.delivered,escrow.released,escrow.refundedescrow.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.
{
"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 bodyx-harrenapay-event— the event name- User-Agent: harrenapay-Webhook/1.0
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.