Integration guide

Signed notifications

Outgoing notifications use a durable transactional outbox. Delivery is at least once, so your receiver must verify and deduplicate.

Configure a receiver

In Developers & Integrations, register its exact HTTPS origin, create a webhook endpoint and select supported events. Save the dedicated endpoint signing secret when shown once. It is different from your API key, hosted signing secret and encryption master key.

Supported events: order.created, order.paid, group.admissions_reserved, ticket.issued, ticket.checked_in, refund.completed. A group slot reservation is not a usable ticket; ticket.issued occurs when a group member claims.

Verify raw bytes before parsing

Check naija-webhook-id, naija-webhook-timestamp and naija-webhook-signature. Compute HMAC-SHA256 of ID.timestamp.rawBody, prefix the hexadecimal signature with v1=, compare in constant time and allow at most 300 seconds of clock skew. Verify integration ID, environment, API version and event type too.

import { createHmac, timingSafeEqual } from "node:crypto";
const expected = createHmac("sha256", endpointSecret)
  .update(`${eventId}.${timestamp}.${rawBody}`).digest();
// Validate exact header formats and timestamp window first.
const supplied = Buffer.from(signature.slice(3), "hex");
const valid = supplied.length === expected.length &&
  timingSafeEqual(supplied, expected);

Acknowledge only after durable recording

Insert the immutable event ID and payload hash into a durable inbox transaction before returning 2xx. Identical duplicates succeed without repeating business effects; conflicting ID/body pairs must not. Return a retryable failure if durable storage is unavailable.

Do not use an in-memory map or local SQLite on Vercel as durable storage. The repository’s SQLite receiver example is for a persistent server. Partner Demo’s public durable receiver still requires configuration and verification.

Daily Hobby dispatch and recovery

The initial Hobby schedule is daily at 04:00 UTC, bounded to twenty delivery attempts per invocation. Timing is not exact and a failed cron invocation is not automatically retried by Vercel. This is not real-time delivery.

Failures use persisted leases, exponential backoff and bounded attempts. Inspect delivery history, fix the cause and use manual retry when eligible. Duplicate/out-of-order notifications remain possible. Alert on exhausted deliveries and growing oldest-pending age; do not infer a payment failure merely from a missing notification.