> For the complete documentation index, see [llms.txt](https://docs.tiun.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tiun.io/reference/webhooks/delivery.md).

# Delivery

This page covers how tiun delivers [webhook events](https://docs.tiun.io/reference/webhooks/events.md) 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](https://my.tiun.business/), 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

* [Webhook events](https://docs.tiun.io/reference/webhooks/events.md) — every event type and its payload.
* [Receiving webhooks](https://docs.tiun.io/guides/webhooks/receive-webhooks.md) — set up an endpoint and write a handler.
* [Sandbox](https://docs.tiun.io/reference/generic/sandbox.md) — why sandbox and live endpoints are set up separately.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.tiun.io/reference/webhooks/delivery.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
