Skip to main content
Webhooks allow external systems to receive real-time notifications about events in your Trackly SMS account.

Available Webhooks

List Event Webhooks

Each sending list can post delivery, reply, unsubscribe, and click events to URLs you configure in the dashboard under your list’s Delivery Forwarding settings. Select Click explicitly to enable clicks; existing subscriptions and the defaults for new webhooks remain unchanged. Each list supports up to 5 webhook endpoints. See Webhook Events for the payload format, delivery semantics, and authentication.

Conversion Attribution

There are three supported ways to get conversion revenue into Trackly:
  1. Platform integration (recommended) — connect TUNE or Everflow on the Integrations page. Trackly pulls your conversion reports automatically on a recurring schedule and attributes revenue to the originating contact via the click identifier Trackly attaches to your tracking links at click time (sub5 on Everflow links, ad_id on TUNE links). No postback setup required.
  2. Per-offer postback URL — each offer’s Postback Config section generates a signed postback URL on your tracking domain that you can paste into your affiliate platform. See Revenue Tracking for the URL format and parameters.
  3. Revenue API — record conversions programmatically, including backfills: record a conversion or bulk upload.

Custom Outbound Webhooks

Account-level outbound webhooks are configured through the API (see Create Endpoint) and signed with HMAC-SHA256. An account supports up to 20 endpoints, each with explicit event subscriptions.

Supported Events

  • message.delivered and message.failed: message delivery outcomes.
  • message.reply: inbound replies.
  • message.clicked: tracked message-link clicks, including bots and repeat clicks; opt in explicitly.
  • contact.opted_out: opt-outs.
  • business_profile.*: the verification events listed in the signed webhook reference.
  • webhook.delivery_dead: an explicitly subscribed retry-exhaustion event in the staged destination-recovery release.
Click events exclude standalone links without a message association. They do not represent conversions; use the conversion attribution methods above for revenue.

Delivery & Retry

Outbound webhooks are delivered as HTTP POST requests with a JSON body and an X-Trackly-Signature HMAC-SHA256 header. If your endpoint returns a non-2xx status, Trackly retries up to 5 times with exponential backoff: After the final retry fails, the delivery is marked dead. Dead deliveries can be re-queued via the bulk replay endpoint.
The HMAC signature above applies to account-level endpoints. List webhooks use an optional X-Webhook-Secret header. List delivery/reply/unsubscribe events remain best-effort without retries; see list click delivery semantics for click retries.

Webhook Security

Shared Secrets & Signatures

List event webhooks include your configured secret in the X-Webhook-Secret header; outbound webhook endpoints are HMAC-SHA256 signed. Always verify before trusting a payload.

HTTPS Required

All webhook endpoints use HTTPS for encrypted communication.

Testing Webhooks

List Events

Use the test button on a saved webhook in your list’s Delivery Forwarding settings to send a sample event. Test → Click sends synthetic click IDs without recording analytics. To test a real click, send a message containing a tracked link and open that link; merely sending a message does not emit a click.

Conversions

Use TUNE’s postback tester to verify conversion tracking.

Troubleshooting

Check:
  • Webhook URL is correctly configured and the webhook is active
  • Endpoint is publicly reachable over HTTPS and returns 200 within 10 seconds
  • No firewall blocking inbound requests
Ensure your handler is idempotent. Dedupe account-level events and list click events on event_id; separate clicks have separate IDs. For legacy list delivery events, a later event can revise an earlier status — dedupe on message_id + status (latest status wins), never on message_id alone.
Verify the postback URL includes all required parameters.

Next Steps

Webhook Events Reference

Event payload format

TUNE Integration

Set up conversion tracking