Add custom HTTP destinations to TrackLayer

Custom destinations exist for the cases where a team needs TrackLayer’s normalization, enrichment, and delivery controls, but the receiver is not a mainstream ad or analytics platform. That often means internal analytics collectors, niche ad platforms, lightweight CDP ingestion endpoints, customer success workflows, or operational webhooks that post directly into Slack or PagerDuty. Instead of building a separate forwarding service for each case, the destination can live next to the rest of the routing layer.

The practical advantage is consistency. The same canonical event that powers a built-in platform integration can also be delivered to an internal endpoint with a custom schema, the same consent state, and the same retry semantics. That makes custom destinations a good fit for systems that need TrackLayer as the source of clean server-side events, but do not justify a full native integration yet.

Configuration happens from /settings/destinations. The page is a placeholder in the current product, but the setup model is straightforward: define the transport, narrow the event filter, shape the payload, choose retry behavior, and then test before exposing the receiver to live traffic.

POST URL
https://hooks.internal.example.com/tracklayer/events

HTTP method
POST

Custom headers JSON
{
  "Authorization": "Bearer {{secrets.webhook_token}}",
  "X-Environment": "production"
}

Signing secret
dest_live_9f3b27

{
  "event_name": ["purchase", "refund_requested"],
  "platform": ["shopify"],
  "segment": ["vip_customers", "b2b_accounts"]
}

{
  "type": "{{event_name}}",
  "timestamp": "{{occurred_at}}",
  "user": {
    "email_hash": "{{user_data.email_hash}}",
    "external_id": "{{user_data.external_id}}"
  },
  "order_id": "{{properties.order_id}}",
  "value": "{{properties.value}}",
  "currency": "{{properties.currency}}"
}

Attempts
5

Backoff
2s, 10s, 30s, 2m, 10m

Synthetic event
purchase

User
qa+destinations@tracklayer.test

Expected outcome
2xx response and visible request in receiver logs

When signing is enabled, TrackLayer computes an HMAC-SHA256 digest of the raw request body and sends it in the X-TrackLayer-Signature header. The receiver should verify the signature before trusting the payload. That means reading the raw bytes exactly as delivered, computing the digest with the shared secret, and comparing it with a timing-safe equality check.

This is the right default for internal APIs and third-party endpoints alike. IP allowlists are useful, but signatures protect against forged requests, replay confusion during debugging, and accidental processing of unauthenticated traffic in environments where multiple services can reach the same endpoint.

import crypto from "node:crypto";

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

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

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

Each custom destination should have its own maximum events-per-second setting so one fragile receiver does not throttle the whole workspace. The right limit depends on the receiver contract, the queue behind it, and how expensive retries become when the target starts returning `429` or timing out under load.

A custom destination should assume that some failures are temporary and some are structural. Timeouts, short outages, and bursty `429` responses usually justify retries with backoff. Persistent `401`, `403`, or schema validation failures usually do not. The point of the retry policy is to give transient failures a recovery path without hiding a broken configuration for hours.

Once retry attempts are exhausted, the event should move to a dead-letter queue instead of disappearing. The DLQ is the operator safety net: it preserves the rendered payload, response code, error message, and destination state so someone can inspect the failure and decide whether to replay, edit the template, rotate a secret, or suppress that route entirely.

This is why idempotency matters on the receiving side. A replay from the DLQ should be safe. If the receiver keys writes on `event_id` or another stable identifier, operational recovery is a normal workflow instead of a duplication risk. Without that, every manual replay becomes a production gamble.

Use a custom destination when the receiver is fundamentally “just an HTTP endpoint” and you need TrackLayer to deliver a shaped, signed request. Use a built-in integration when the platform has a first-class API contract, ongoing vendor quirks, or authentication flows that TrackLayer should manage directly.

Need a TrackLayer destination?
→ Built-in platform already exists
  → Use the built-in integration
→ No built-in platform exists
  → Receiver accepts generic HTTP
    → Use a custom destination
  → Receiver needs OAuth refreshes, complex object sync, or evolving vendor-specific schemas
    → Build or request a native integration instead