paytrack docs

Webhooks

Receive signed event notifications when important paytrack activity happens.

What webhooks are

Webhooks let paytrack call your HTTPS endpoint when customers, tracks, payments, reminders, and reports change. Use them to sync external CRMs, accounting tools, and internal operations systems.

Create an endpoint

Open Developer, then Webhooks. Add an HTTPS URL, select events, and copy the signing secret. The secret is shown once and should be stored like an API key.

HTTPS required

paytrack rejects non-HTTPS webhook endpoints.

Supported events

customer.createdcustomer.updatedtrack.createdtrack.updatedtrack.overduepayment.recordedpayment.failedreminder.sentreminder.failedreport.generated

Sample payload

Example

{
  "id": "evt_123",
  "type": "payment.recorded",
  "workspace_id": "wsp_123",
  "created_at": "2026-07-08T10:00:00.000Z",
  "data": {
    "payment": {
      "id": "pay_123",
      "amount": 25000,
      "currency": "NGN",
      "track_id": "trk_123"
    }
  }
}

Signature verification

Verify the raw request body with HMAC SHA-256 and your endpoint signing secret before trusting the payload.

Example

import crypto from "node:crypto";

function verifyPaytrackWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Retries and failed deliveries

Webhook deliveries are recorded with status, response code, attempts, and response text. Failed deliveries should be retried after transient errors and inspected when an endpoint keeps returning non-2xx responses.

Testing

Use the Webhooks page to send a test event. This creates a delivery record so you can confirm your endpoint receives and verifies the payload correctly.

Related docs

API keys Testing Errors

{ "id": "evt_123", "type": "payment.recorded", "workspace_id": "wsp_123", "created_at": "2026-07-08T10:00:00.000Z", "data": { "payment": { "id": "pay_123", "amount": 25000, "currency": "NGN", "track_id": "trk_123" } } }

Signature verification

Verify the raw request body with HMAC SHA-256 and your endpoint signing secret before trusting the payload.

Example

import crypto from "node:crypto";

function verifyPaytrackWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}