After the payment
Webhooks
The only thing that should ever mark an order paid.
A webhook is Harbour telling your server that something happened, signed so you can prove it came from Harbour. It
is the only thing that should ever mark an order paid. Everything else — the return URL, onSuccess, a
customer's word — is a hint.
Add an endpoint
In the dashboard, Settings → Developers → Webhook endpoints: paste your URL, choose the mode, and
copy the whsec_… secret shown once. Points worth knowing:
- Each endpoint has its own secret and its own mode, so test deliveries never hit live code.
- The URL must be reachable from the internet over HTTPS in live mode. Private, loopback and metadata addresses are refused, at save and again at delivery.
- Test endpoint on that screen sends a real signed delivery, so you can prove the wiring before a customer does.
- Adding an endpoint needs API & webhooks on the business's plan (Growth and up, see Keys). Endpoints already added keep receiving deliveries whatever the plan.
Verify every delivery
Harbour-Signature: t=1757764935,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
v1 = hex(HMAC_SHA256(endpoint_secret, t + "." + raw_request_body))
handle() checks that HMAC in constant time, rejects a timestamp more than 300 seconds
from now (so an old delivery cannot be replayed at you), and only then calls your closure with a typed
Event:
import express from 'express';
import { Harbour, Event, SignatureVerificationError } from '@nordaxiz/harbour-connect';
const harbour = new Harbour(process.env.HARBOUR_SECRET_KEY, {
webhookSecret: process.env.HARBOUR_WEBHOOK_SECRET,
});
// before app.use(express.json()): the signature is checked against the raw bytes
app.post('/webhooks/harbour', express.raw({ type: 'application/json' }), async (req, res) => {
let event;
try {
event = harbour.webhooks.constructEvent(req.body, req.headers);
} catch (e) {
if (e instanceof SignatureVerificationError) return res.sendStatus(400); // not ours, or tampered with
throw e;
}
// deliveries repeat: if you have seen this event id, stop here
if (await WebhookLog.seen(event.id)) return res.sendStatus(200);
await WebhookLog.record(event.id, event.type);
switch (event.type) {
case Event.CHARGE_SUCCEEDED: await fulfil(event.transaction()); break;
case Event.CHARGE_FAILED: await noteFailure(event.transaction()); break;
case Event.REFUND_COMPLETED: await creditBack(event.refund()); break;
case Event.LINK_PAID: await markInvoicePaid(event.transaction()); break;
}
res.sendStatus(200);
});
<?php
use Nordaxiz\HarbourConnect\Exception\SignatureVerificationException;
use Nordaxiz\HarbourConnect\Harbour;
use Nordaxiz\HarbourConnect\Webhook\Event;
try {
Harbour::webhooks((string) getenv('HARBOUR_WEBHOOK_SECRET'))->handle(null, function (Event $event): void {
// deliveries repeat: if you have seen this event id, stop here
if (WebhookLog::seen($event->id)) {
return;
}
WebhookLog::record($event->id, $event->type);
match ($event->type) {
Event::CHARGE_SUCCEEDED => fulfil($event->transaction()),
Event::CHARGE_FAILED => noteFailure($event->transaction()),
Event::REFUND_COMPLETED => creditBack($event->refund()),
Event::LINK_PAID => markInvoicePaid($event->transaction()),
default => null,
};
});
http_response_code(200);
} catch (SignatureVerificationException $e) {
http_response_code(400); // not ours, or tampered with: do not retry it
}
Passing null reads the raw body from php://input and the headers from the server. In a
framework, hand it the request object you already have:
// any framework: pass the raw body and the headers, or the Harbour-Signature value alone
// Express, Fastify, Koa: the raw Buffer and the headers object
harbour.webhooks.constructEvent(req.body, req.headers);
// the Fetch API (Next.js route handlers, Hono): the text and the Headers
harbour.webhooks.constructEvent(await request.text(), request.headers);
// the header value on its own
harbour.webhooks.constructEvent(rawBody, signatureHeader);
// without a client: one Webhooks per endpoint secret
import { Webhooks } from '@nordaxiz/harbour-connect';
const webhooks = new Webhooks(process.env.HARBOUR_WEBHOOK_SECRET);
<?php
// any framework: hand the handler the request you already have
$handler = Harbour::webhooks((string) getenv('HARBOUR_WEBHOOK_SECRET'));
$handler->handle($psrServerRequest, $fn); // PSR-7
$handler->handle($symfonyOrLaravelRequest, $fn); // Symfony / Laravel
$handler->handle(['body' => $raw, 'headers' => $heads], $fn);
$handler->handle($rawBody, $fn, ['Harbour-Signature' => $header]);
// or verify yourself and get the Event back
$event = $handler->constructEvent($rawBody, $signatureHeader);
The events
| Event | data is | Means |
|---|---|---|
charge.succeeded | transaction | Money was taken. Fulfil the order. |
charge.failed | transaction | The attempt failed. failure_message says why. |
link.paid | transaction | A payment link was paid. |
refund.requested | refund | Someone asked for a refund; it is waiting for approval. |
refund.completed | refund | The provider sent the money back. |
refund.failed | refund | The provider refused or could not complete it. |
refund.declined | refund | An Owner declined the request. |
settlement.landed | settlement | A payout reached the bank account. |
settlement.short | settlement | A payout landed short of the forecast. |
invoice.issued | invoice | A Harbour Invoice got its number and can be paid. |
invoice.paid | invoice | The invoice is paid in full. |
invoice.overdue | invoice | The due date passed with money still owed. |
invoice.voided | invoice | The business cancelled the invoice. |
order.paid | order | A StoreFront or Tickets order was paid. |
order.fulfilled | order | The business marked the order sent. |
order.refunded | order | The order was refunded in full. |
registration.submitted | registration | Someone asked for an approval ticket. |
registration.approved | registration | The organiser approved it; the attendee got a link to pay. |
registration.declined | registration | The organiser declined it. |
ticket.issued | ticket | A ticket was issued after payment. |
ticket.checked_in | ticket | A ticket was scanned in at the door. |
event.published | event | An event went on sale. Sent in each mode Tickets is on, so test and live websites both hear it. |
event.updated | event | A published event changed: its details, pictures, ticket types, prices or seats. |
event.cancelled | event | The organiser cancelled the event. |
event.deleted | event ("deleted": true) | The organiser deleted an event that was on sale but never took an order. Take it off your site. |
They are constants on Event (Event.CHARGE_SUCCEEDED in Node.js,
Event::CHARGE_SUCCEEDED in PHP). transaction(), refund() and paymentLink()
return the object when the payload matches, and event.data always holds the raw payload. Ignore event types you do not handle; more will be added.
What a delivery looks like
{
"id": "evt_01k5m0r3w9a2c8n7xq4v6t1b0d",
"type": "charge.succeeded",
"created_at": "2026-09-13T14:32:09Z",
"mode": "live",
"tenant_id": "ten_01m2e48qxzwqrwz0axj3r20jpv",
"data": {
"object": "transaction",
"id": "txn_01k5m0r3w9a2c8n7xq4v6t1b0d",
"reference": "HB-88413",
"merchant_reference": "order-1043",
"type": "charge",
"status": "succeeded",
"provider": "paystack",
"provider_reference": "PSK_8h2k9d0f",
"amount_kobo": 1200000,
"fee_kobo": 18000,
"net_kobo": 1182000,
"refunded_kobo": 0,
"currency": "NGN",
"channel": "card",
"customer": { "name": "Funke Adeyemi", "email": "funke@example.ng", "phone": null },
"failure_message": null,
"occurred_at": "2026-09-13T14:32:07Z",
"settled_at": null,
"settlement_id": null,
"recovered": false,
"metadata": { "order_id": "1043" },
"mode": "live"
}
}
The five rules
- Verify, always. An unverified POST is a stranger with your URL.
- De-duplicate on
id. A retry, or a provider sending the same event twice, must not ship the goods twice. Store the event id with a unique index and return early. - Check the money. Match
merchant_referenceandamount_koboagainst your own record before fulfilling. - Answer fast. 2xx within ten seconds. Queue anything slower: emails, PDFs, stock updates.
- Be honest with status codes. 2xx means "I have it". Anything else is retried at 1m, 5m, 30m, 2h, 6h and 12h for up to 24 hours. A 400 for a bad signature is correct; a 500 because your database blinked is also correct, and Harbour will come back.
async function fulfil(txn) {
const order = await Order.findByReference(txn.merchant_reference);
// three checks before money means anything
if (!order) return;
if (order.totalKobo !== txn.amount_kobo) { await alertFinance(order, txn); return; }
if (order.isPaid()) return;
await order.markPaid(txn.reference);
await queue.add('send-receipt', { orderId: order.id }); // slow work never happens in the request
}
<?php
use Nordaxiz\HarbourConnect\Model\Transaction;
function fulfil(Transaction $transaction): void
{
$order = Order::findByReference($transaction->merchantReference);
// three checks before money means anything
if ($order === null) { return; }
if ($order->total_kobo !== $transaction->amountKobo) { alertFinance($order, $transaction); return; }
if ($order->isPaid()) { return; }
$order->markPaid($transaction->reference);
Queue::push(new SendReceipt($order)); // slow work never happens in the request
}
Testing without a public URL
You do not need a tunnel to test your handler. Sign a payload the way Harbour does and post it at yourself:
import { readFileSync } from 'node:fs';
import { Signature } from '@nordaxiz/harbour-connect';
// build a delivery exactly as Harbour signs one, and post it at your own endpoint
const body = readFileSync('fixtures/charge.succeeded.json', 'utf8');
const header = Signature.header(body, 'whsec_your_endpoint_secret');
const res = await fetch('http://localhost:3000/webhooks/harbour', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'Harbour-Signature': header },
body,
});
console.log(res.status);
BODY=$(cat fixtures/charge.succeeded.json)
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "whsec_your_endpoint_secret" | sed 's/^.* //')
curl -s -X POST http://localhost:3000/webhooks/harbour \
<?php
use Nordaxiz\HarbourConnect\Webhook\Signature;
// build a delivery exactly as Harbour signs one, and post it at your own endpoint
$body = file_get_contents(__DIR__ . '/fixtures/charge.succeeded.json');
$header = Signature::header($body, 'whsec_your_endpoint_secret');
$ch = curl_init('http://localhost:8000/webhooks/harbour');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $body,
CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Harbour-Signature: ' . $header],
CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);
That is real end-to-end coverage of your endpoint: the signature, the parsing, the de-duplication and the fulfilment. More on this, including what to assert, on Testing.