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

HTTP
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:

webhook
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);
});

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);

The events

Eventdata isMeans
charge.succeededtransactionMoney was taken. Fulfil the order.
charge.failedtransactionThe attempt failed. failure_message says why.
link.paidtransactionA payment link was paid.
refund.requestedrefundSomeone asked for a refund; it is waiting for approval.
refund.completedrefundThe provider sent the money back.
refund.failedrefundThe provider refused or could not complete it.
refund.declinedrefundAn Owner declined the request.
settlement.landedsettlementA payout reached the bank account.
settlement.shortsettlementA payout landed short of the forecast.
invoice.issuedinvoiceA Harbour Invoice got its number and can be paid.
invoice.paidinvoiceThe invoice is paid in full.
invoice.overdueinvoiceThe due date passed with money still owed.
invoice.voidedinvoiceThe business cancelled the invoice.
order.paidorderA StoreFront or Tickets order was paid.
order.fulfilledorderThe business marked the order sent.
order.refundedorderThe order was refunded in full.
registration.submittedregistrationSomeone asked for an approval ticket.
registration.approvedregistrationThe organiser approved it; the attendee got a link to pay.
registration.declinedregistrationThe organiser declined it.
ticket.issuedticketA ticket was issued after payment.
ticket.checked_inticketA ticket was scanned in at the door.
event.publishedeventAn event went on sale. Sent in each mode Tickets is on, so test and live websites both hear it.
event.updatedeventA published event changed: its details, pictures, ticket types, prices or seats.
event.cancelledeventThe organiser cancelled the event.
event.deletedevent ("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

JSON charge.succeeded
{
  "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

  1. Verify, always. An unverified POST is a stranger with your URL.
  2. 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.
  3. Check the money. Match merchant_reference and amount_kobo against your own record before fulfilling.
  4. Answer fast. 2xx within ten seconds. Queue anything slower: emails, PDFs, stock updates.
  5. 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.
The fulfil step, in full
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
}

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:

send a test delivery
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);

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.