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 isapplication/json.
event_idis minted once per logical event and shared across all endpoints, retries, and replays — dedupe on it (see below).account_external_idscarries the external IDs of the child the event belongs to, so a single receiver can route across your whole portfolio.attemptstarts at1and increments on each retry.
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
- Read
X-Trackly-Signatureand parse thet(timestamp) andv1(signature) parts. - Reject the request if
tis more than 300 seconds from your current time — this bounds replay. - Compute
HMAC-SHA256(signing_secret, "{t}.{raw_body}")as a hex string, whereraw_bodyis the exact raw request body bytes (do not re-serialize the parsed JSON — key order and whitespace must match). - Compare your computed value to
v1using a constant-time comparison. - During a secret rotation, if
v1doesn’t match, repeat the check againstX-Trackly-Signature-Prevwith your previous secret before rejecting.
Delivery semantics
- At-least-once and unordered. A carrier receipt can be redelivered and a status can be revised (e.g.
deliveredlater corrected tofailed). Dedupe onevent_id, and let the latest received state win. - Retries with backoff. A non-
2xxresponse (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 markeddeadand 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 inX-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 olddead 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.
Related
Create an endpoint
Register an HTTPS endpoint to receive events.
Deliveries & replay
Inspect the delivery log and replay events.