Webhooks

Open Developer, then Webhooks. Add an HTTPS URL and select events. The signing secret is shown exactly once; store it in your server-side secret manager. Existing endpoints that predate encrypted secret storage show Secret rotation required and do not receive deliveries until you rotate their secret.

Only the event types below are currently emitted. Customer events cover creation and updates; payment events cover installment-track payments, including manual, public API, Paystack checkout, and virtual-account reconciliation paths.

{
  "id": "evt_123",
  "type": "payment.recorded",
  "api_version": "1.0",
  "created_at": "2026-08-20T10:00:00.000Z",
  "workspace_id": "wsp_123",
  "data": {
    "payment": {
      "id": "pay_123",
      "track_id": "trk_123",
      "customer_id": "cus_123",
      "amount": 25000,
      "method": "Bank Transfer",
      "paid_at": "2026-08-20T09:59:58.000Z",
      "created_at": "2026-08-20T10:00:00.000Z"
    }
  }
}

Use event.id as your idempotency key. Every retry of one delivery keeps the same event ID. Test deliveries use webhook.test and are marked separately in paytrack.

Read the request as an exact raw string or byte array before parsing JSON. The paytrack-signature header is t=<unix_seconds>,v1=<hex_hmac>, where the digest is HMAC-SHA256 over timestamp.raw_body. Reject timestamps outside five minutes to limit replay.

import { verifyWebhookSignature } from "@paytrack/sdk";

verifyWebhookSignature({
  payload: rawRequestBody,
  signature: request.headers.get("paytrack-signature"),
  secret: process.env.PAYTRACK_WEBHOOK_SECRET,
});

const event = JSON.parse(rawRequestBody);
// Atomically record event.id before processing it.

Business requests only queue events; a background worker performs delivery. A 2xx response succeeds. Network failures, timeouts, 429, and 5xx responses retry after 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours, and 24 hours. Other 4xx responses and redirects fail immediately. A safe Retry-After value on 429 may extend the next delay. Delivery stops after seven total attempts.

Delivery history shows event ID/type, test status, attempts, HTTP status, duration, failure category, and next retry. Downstream response bodies are never persisted.

Use Rotate signing secret when a secret is lost, exposed, or required for a legacy endpoint. The old secret stops working immediately and the replacement is displayed once. paytrack stores only its hash and authenticated encrypted ciphertext.

Send test queues a normal asynchronous delivery with a webhook.test envelope. It does not create or alter a customer or payment.