Skip to main content
Partner webhooks are account-level endpoints you register through the webhook management API. Every event Trackly delivers to them is signed with HMAC-SHA256 so you can prove it came from Trackly and wasn’t replayed or tampered with.
This is the partner webhook control plane — account-level endpoints, HMAC-signed, retried with backoff, managed over the API. Per-list Delivery Forwarding webhooks use an optional shared-secret header and an events array; their retry behavior depends on the event type. This page describes account-level endpoints.

Event types

A registered endpoint subscribes to one or more of:
business_profile.* events carry business_profile_id and verification_status in their data object — fetch the profile or its submissions for the full detail.
webhook.delivery_dead carries endpoint_id, the exhausted delivery’s event_id, attempt_count, and endpoint_disabled in data. Its own failed delivery never emits another webhook.delivery_dead event. This optional event supplements the independent destination-disable notices described below; it does not replace them.

The event envelope

Each POST body is a single event (not a batch). Content type is application/json.
  • event_id is minted once per logical event and shared across all endpoints, retries, and replays — dedupe on it (see below).
  • account_external_ids carries the external IDs of the child the event belongs to, so a single receiver can route across your whole portfolio.
  • attempt starts at 1 and increments on each retry.
For message.clicked, data contains the click fields. data.clicked_at is the original capture time and remains unchanged across retries and replay; the envelope’s created_at describes the current send. data.list_id can be null when the message and account are verified but a valid sending list cannot be resolved. Standalone links without a message association do not emit message.clicked.

Signature headers

How to verify

  1. Read X-Trackly-Signature and parse the t (timestamp) and v1 (signature) parts.
  2. Reject the request if t is more than 300 seconds from your current time — this bounds replay.
  3. Compute HMAC-SHA256(signing_secret, "{t}.{raw_body}") as a hex string, where raw_body is the exact raw request body bytes (do not re-serialize the parsed JSON — key order and whitespace must match).
  4. Compare your computed value to v1 using a constant-time comparison.
  5. During a secret rotation, if v1 doesn’t match, repeat the check against X-Trackly-Signature-Prev with your previous secret before rejecting.
The signing secret is returned once when you create the endpoint (and again on rotation). Store it securely.

Delivery semantics

  • At-least-once and unordered. A carrier receipt can be redelivered and a status can be revised (e.g. delivered later corrected to failed). Dedupe on event_id, and let the latest received state win.
  • Retries with backoff. A non-2xx response (or a timeout — your endpoint must answer within 10 seconds) receives up to five retries after 60, 300, 900, 3600, and 14400 seconds. After the initial attempt and those retries fail, the delivery is marked dead and its retained history remains available.
  • Replayable. Retained deliveries can be re-sent from the deliveries API, reusing the original event_id. Terminal history remains available for 30 days from the delivery’s original creation; pending work is retained until it settles.
  • HTTPS only. Endpoints must be https:// public URLs; Trackly pins the resolved IP and does not follow redirects.

Rotating the signing secret

Rotate the secret and the old secret keeps working for a 24-hour grace window. During that window events are signed with the new secret in X-Trackly-Signature and the old secret in X-Trackly-Signature-Prev, so you can deploy the new secret with zero missed events. After the window, only the new secret is used.

Destination failure and recovery

Destination failure controls, independent notices, and dashboard recovery controls are staged additions. Their availability depends on the release of the API, dashboard, and delivery updates; this page does not establish that they are active for your account. A failed attempt starts that endpoint’s failure window. A successful attempt resets the window. Only a new failed attempt strictly more than 24 hours after the uninterrupted window began disables delivery to that destination. A failure at exactly 24 hours does not qualify. Time passing without another failed attempt, an old dead record, and retry exhaustion alone do not disable it. Other destinations and SMS sending and reply processing continue. Each disable incident owns one in-platform notice and one email notification to the account owner, delivered independently of your customer webhook endpoints. No webhook subscription is required, and notices do not depend on having a remaining configured endpoint. Notification retries and restarts retain the same incident instead of generating a notice for every exhausted delivery. Email prioritizes delivery and can arrive more than once after an uncertain submission; those copies refer to the same incident. Review the endpoint’s delivery history and incident history in Developers > Webhooks when those dashboard controls are available. Repair the destination, send a test, then explicitly re-enable it in the dashboard or with PATCH {"active": true}. Testing does not clear the failure state or silently re-enable delivery. Re-enable clears current operational failure state while retaining history; replay retained events if your receiver still needs them. These controls apply to account-level endpoints. Per-list Delivery Forwarding integration is a separate pending release; its current wire and delivery contract remains separate.

Create an endpoint

Register an HTTPS endpoint to receive events.

Deliveries & replay

Inspect the delivery log and replay events.