TrackLayer webhooks: subscribe to events, deliveries, anomalies

TrackLayer webhooks are operational notifications, not just event copies. They exist so another system can react when routing succeeds, fails, drifts, or produces a file that is ready to consume. In practice, that means you can wire webhooks into chat, incident response, internal dashboards, support tooling, or batch workflows without adding a polling job around the TrackLayer API.

The key design rule is to treat each webhook type as its own contract. Some messages describe delivery outcomes, some describe monitoring state, and some describe asynchronous job completion. Your endpoint can be shared, but each topic should still have dedicated validation and ownership.

Every TrackLayer webhook has the same outer envelope even though the nested `data` payload changes by topic. That consistency is what lets you build one receiver, one signature verification layer, one dedup store, and one audit log format. Start by validating the canonical fields at the top level before you route deeper into the message.

{
  "id": "wh_01HSV5DZJ7M9J9J6XQ4N8Q5K4A",
  "type": "event.delivered",
  "created_at": "2026-04-23T09:41:22Z",
  "data": {
    "destination": "meta_capi",
    "workspace_id": "ws_7k2p9f",
    "event_id": "evt_01HSV5DW7QG9M2M7T8V9P4Z6A1",
    "destination_event_id": "meta:7019284411",
    "status": "delivered",
    "attempt": 1,
    "latency_ms": 184,
    "received_at": "2026-04-23T09:41:21Z",
    "delivered_at": "2026-04-23T09:41:22Z",
    "customer": {
      "external_id": "cust_10492",
      "email_hash": "9c2f6b9c7d56d6b52d3ff7d3b4c6c1ef"
    },
    "properties": {
      "event_name": "Purchase",
      "value": 129.95,
      "currency": "EUR",
      "order_id": "10492"
    }
  }
}

TrackLayer signs every webhook with HMAC-SHA256 and sends the digest in the `X-TrackLayer-Signature` header. The verification input is the raw request body exactly as received. That detail matters because any middleware that parses and re-serializes JSON can change whitespace, key order, or encoding and break a valid signature check.

The normal handler sequence is: capture raw bytes, compute the HMAC using your shared secret, compare with the header using a timing-safe comparison, reject on mismatch, then parse and route the body. If your framework makes raw body access awkward, solve that first. Signature verification that runs against a mutated payload is worse than no verification because it fails unpredictably in production.

import crypto from "node:crypto";

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

  const received = signatureHeader?.replace(/^sha256=/, "") ?? "";

  return (
    expected.length === received.length &&
    crypto.timingSafeEqual(
      Buffer.from(expected, "utf8"),
      Buffer.from(received, "utf8"),
    )
  );
}

import hashlib
import hmac


def verify_tracklayer_signature(raw_body: bytes, signature_header: str, secret: str):
    expected = hmac.new(
        secret.encode("utf-8"),
        raw_body,
        hashlib.sha256,
    ).hexdigest()

    received = (signature_header or "").removeprefix("sha256=")
    return hmac.compare_digest(expected, received)

Webhooks should be designed with the assumption that downstream systems are occasionally slow, unavailable, or mid-deploy. TrackLayer retries failed deliveries with exponential backoff. The receiving side should therefore distinguish between transient problems and permanent schema or auth failures, because every non 2xx response extends the total recovery window.

The table below shows the backoff schedule. After the exponential cycle completes, the message moves to a dead-letter queue for operator review or replay. That is another reason idempotency matters: a manual replay should be operationally safe.

Webhook delivery is at-least-once by design. That means your consumer must tolerate duplicate delivery without producing duplicate side effects. The correct dedup key is the top-level `id` field, not a combination of timestamps, types, or nested data values that may be harder to reason about later.

A practical pattern is to write the webhook `id` into a durable store with status fields such as `received`, `processing`, `processed`, and `failed`. On a duplicate delivery, short-circuit and return success if the message was already accepted or completed. That way retries, replay tooling, and race conditions collapse to one outcome even when your handler is scaled across multiple workers.

dedup_key = webhook.id

if store.exists(dedup_key):
    return 200

store.insert(dedup_key, status="received")
queue.enqueue(webhook)
return 202

Local webhook work is mostly about inspecting exact requests and iterating quickly on signature verification, schema handling, and response behavior. You do not need a full staging deployment just to prove the integration path. A tunnel or request bin is usually enough for the first pass.

Use ngrok when you want raw replay and a mature inspect UI. Use Cloudflare Tunnel if your team already routes development ingress through Cloudflare. Use Hookbin before you write code, when the immediate need is to inspect headers, payload shape, and event sequencing during development.