> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Webhooks

> Receive events via webhooks for custom integrations

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`, and `unsubscribe` events to URLs you configure in the dashboard under your list's **Delivery Forwarding** settings. Use these to sync delivery outcomes and inbound messages into your own systems in real time.

See [Webhook Events](/api-reference/v2/webhooks/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, Everflow, or Cake 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](/guides/offers/revenue-tracking) for the URL format and parameters.
3. **Revenue API** — record conversions programmatically, including backfills: [record a conversion](/api-reference/v2/revenue/record-revenue) or [bulk upload](/api-reference/v2/revenue/bulk-revenue).

## Custom Outbound Webhooks

Trackly supports outbound webhooks that send real-time event notifications to your systems. Outbound webhooks use the `WebhookEndpoint` configuration model with HMAC-SHA256 request signing for authenticity verification.

### Supported Events

* Message sent events
* Click events
* Conversion events
* Opt-out events

### 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:

| Attempt   | Delay      |
| --------- | ---------- |
| 1st retry | 1 minute   |
| 2nd retry | 5 minutes  |
| 3rd retry | 15 minutes |
| 4th retry | 1 hour     |
| 5th retry | 4 hours    |

After the final retry fails, the delivery is marked `dead`. Dead deliveries can be re-queued via the [bulk replay endpoint](/api-reference/v2/webhooks/bulk-replay).

<Note>
  The retry policy and HMAC signature above apply to the outbound `WebhookEndpoint` system. List event webhooks (delivery/reply/unsubscribe) are fire-and-forget with a shared-secret header — see [Webhook Events](/api-reference/v2/webhooks/events#delivery-semantics).
</Note>

## Webhook Security

### Shared Secrets & Signatures

List event webhooks include your configured secret in the `X-Webhook-Secret` header; outbound `WebhookEndpoint` webhooks 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 your list's **Delivery Forwarding** settings to send a sample event, or send a test message and monitor for the delivery event.

### Conversions

Use TUNE's postback tester to verify conversion tracking.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Webhooks not arriving">
    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
  </Accordion>

  <Accordion title="Duplicate webhooks">
    Ensure your handler is idempotent — events are delivered at-least-once, and a later delivery event can revise an earlier status. Dedupe delivery events on `message_id` + `status` (latest status wins), never on `message_id` alone.
  </Accordion>

  <Accordion title="Missing data in webhook">
    Verify the postback URL includes all required parameters.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Webhook Events Reference" icon="code" href="/api-reference/v2/webhooks/events">
    Event payload format
  </Card>

  <Card title="TUNE Integration" icon="plug" href="/guides/offers/tune-integration">
    Set up conversion tracking
  </Card>
</CardGroup>