Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Delivery

This page covers how tiun delivers webhook events to your endpoints: what counts as success, how failed deliveries are retried, and how to follow them in the dashboard.


The request

Each event is sent as an HTTP POST to the endpoint URL, with the event as a JSON body. Endpoint URLs must use https://.

One event is one request. If several endpoints are subscribed to the same event, each gets its own delivery, retried independently.


Success and failure

Your response
Result

Any 2xx status within 15 seconds

Delivered. No more attempts.

A 4xx or 5xx status

Failed attempt. The delivery is retried.

No response within 15 seconds

Timeout. The delivery is retried.

No connection — DNS, TLS, or network error

Failed attempt. The delivery is retried.

Reply as soon as you've received the event, and do any slow work — API calls, database writes, emails — after responding. A handler that takes longer than 15 seconds is treated as a failure even if it finishes the work.


Retries

A delivery gets up to 10 attempts: the first one, then retries with increasing delays between them, spread over about 48 hours. If none of them gets a 2xx response, the delivery is marked Failed and tiun stops trying.

Because of retries, design your handler around two rules:

  • Expect duplicates. An event can reach you more than once — for example if your server did the work but the response got lost, or if you resend a delivery. Every attempt carries the same event id; store the IDs you've handled and skip repeats.

  • Don't rely on order. A retried event can arrive after a newer one. Rather than applying events in sequence, re-read the user's current state from the API each time, so the latest answer always wins.


Delivery statuses

Each delivery has one of these statuses in the dashboard:

Status
Meaning

Scheduled

Waiting for its first attempt.

Retrying

An attempt failed; another one is scheduled. The dashboard shows when.

Succeeded

Your endpoint returned a 2xx response.

Failed

All attempts failed. tiun won't try again on its own.

Cancelled

tiun stopped delivering it before it succeeded.


Monitoring and resending

In the dashboard, open API & Webhook → Webhooks and select an endpoint to see:

  • Deliveries, failures, delivery rate, and average response time over the last 24 hours, 7 days, or month.

  • Every delivery with its status, HTTP response code, and response time. Open one to see the event body and each individual attempt, including your server's response.

To deliver an event again — for example after fixing an outage that caused a Failed delivery — resend it from the delivery in the dashboard. It sends the real event again, with the same id.

A test event, sent from the endpoint, is different: it's a sample event with placeholder IDs, so you can check your handler without real data.


Pausing an endpoint

Pausing an endpoint stops tiun from sending events to it until you turn it back on. Events that happen while it's paused aren't delivered to it — not when they happen, and not after you enable it again — so if your systems rely on them, re-sync from the API afterwards. You can't send test events to a paused endpoint. To stop receiving events for good, delete the endpoint instead.


Where to go next

Last updated

Was this helpful?