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

# Event delivery

Learn what events, deliveries and attempts are, what their statuses mean, and how retries and resends work.

When something changes for one of your users, Terra creates an **event** and sends it to your destinations. Three objects describe that journey:

* An **event** is the thing that happened, such as new sleep data or a user connecting a provider.
* A **delivery** is that event on its way to one destination. An event has one delivery per destination.
* An **attempt** is one request Terra sends for a delivery. A delivery has one attempt per send, retry and resend.

## An example

A user's sleep syncs. Your environment has two destinations: a webhook and an S3 bucket. Your webhook server was down for a few minutes.

```mermaid
flowchart TB
    E["<b>Event</b><br/>evt_123<br/>unified_api.sleep.updated"]
    D1["<b>Delivery</b><br/>webhook<br/>api.example.com/terra"]
    D2["<b>Delivery</b><br/>s3<br/>my-bucket"]
    A1["<b>Attempt 1</b><br/>10:00:02 · 503"]
    A2["<b>Attempt 2</b><br/>10:01:05 · 503"]
    A3["<b>Attempt 3</b><br/>10:05:40 · 200"]
    A4["<b>Attempt 1</b><br/>10:00:03 · 200"]

    E --> D1
    E --> D2
    D1 --> A1
    D1 --> A2
    D1 --> A3
    D2 --> A4

    classDef failed stroke:#F04438,stroke-width:2px
    classDef ok stroke:#12B76A,stroke-width:2px
    class A1,A2 failed
    class A3,A4 ok
```

* There is **one event**, because one thing happened.
* There are **two deliveries**, because there are two destinations.
* The webhook delivery took **three attempts**: two failed while the server was down, and a retry succeeded.
* The bucket delivery took **one attempt**. The webhook's failures did not delay it.

Each delivery succeeds or fails on its own. One broken destination never holds back the others.

## Event IDs and types

Every event has an `event_id`. Your webhook receives it in the `terra-reference` header. Every delivery, retry and resend of an event carries the same `event_id`, so use it to recognise an event you have already processed.

An event's `type` says what happened, in the form `<product>.<resource>.<action>`, for example `unified_api.sleep.updated` or `unified_api.auth.succeeded`. See [Event types](https://docs.tryterra.co/reference/health-and-fitness-api/event-types) for the payload each one carries.

## Delivery status

Start with the delivery. Its status says where the event stands for one destination.

| Status      | Meaning                                                                                                              |
| ----------- | -------------------------------------------------------------------------------------------------------------------- |
| `pending`   | Not delivered yet. Terra tries again at `next_attempt_at`.                                                           |
| `delivered` | The destination accepted the event. For a webhook, that means a 2xx response.                                        |
| `failed`    | Terra sent at least one request, then stopped trying. Usually the retries ran out.                                   |
| `canceled`  | Terra decided not to send before sending any request, for example because the destination was deleted or turned off. |

To see why a delivery failed or was canceled, look at its last status code. When there is no HTTP status to show, `no_status_reason` explains instead, for example `timed_out` or `destination_deleted`.

## Event status

An event's status sums up its deliveries, so you can scan a list of events without opening each one.

| Status      | Meaning                                                                                     |
| ----------- | ------------------------------------------------------------------------------------------- |
| `pending`   | At least one delivery is still `pending`.                                                   |
| `failed`    | No delivery is pending, and at least one `failed`.                                          |
| `canceled`  | Every delivery was `canceled`. No destination was sent the event.                           |
| `delivered` | Every other case: each destination got the event, or was canceled after another one got it. |

A `failed` event may still have reached some of your destinations. Open it to see which delivery failed.

## Retries

When an attempt fails, the delivery stays `pending` and Terra tries again later, with exponential backoff, for several hours. An attempt fails when the destination returns anything other than a 2xx, does not answer within 8 seconds, or cannot be reached. Retries always go to the destination's current URL.

When the retries run out, the delivery becomes `failed` and Terra stops trying. Terra does not notify you when this happens, so monitor your endpoint, or check the Events page for failed events.

The number and timing of retries can change, so don't depend on a specific schedule. For timeouts and the circuit breaker that pauses a failing webhook, see [Webhooks](https://docs.tryterra.co/destinations/webhooks.md#timeout-and-circuit-breaker).

## Resends

A resend sends an event to one destination again. It adds new attempts to that destination's existing delivery, each marked with the resend's `resend_id`. It does not create a new event or a new delivery. A resend runs alongside any automatic retries rather than replacing them.

Resend failed events once your destination is fixed. Your server can receive the same event more than once, so deduplicate on `event_id`.

## View and resend events

* **Dashboard:** the [Events](https://dashboard.tryterra.co/dashboard/debug) page lists events for 30 days. Open one to see each delivery, every attempt, and when the next retry is due. You can view an event's payload for about 14 days, and resend it from there.
* **Terra CLI:** `terra events list --status failed` finds failed events, `terra events retrieve <EVENT_ID>` shows their deliveries and attempts, and `terra events resend` sends one again. See the [command reference](https://docs.tryterra.co/developer-tools/terra-cli/command-reference).

{% prompt description="Find failed events and resend them" icon="terminal" openInAIProviders="true" defaultExpanded="full" %}

```markdown
Show me every failed event in production from the last 24 hours, tell me which destination each one failed on and why, and resend the ones for user 9ebfb96d-e376-4c17-8d4b-0e85db39b1b5.

Use the Terra CLI: brew install tryterra/tap/terra, or npm install -g @tryterra/cli, then terra login. Run terra docs ask --question "<question>" for anything you need from the Terra docs, and terra <command> --help for usage.
```

{% endprompt %}

## Next steps

* [Health data events](https://docs.tryterra.co/unified-api/receiving-data-updates.md): handle the data events Terra sends for connected users.
* [Historical data requests](https://docs.tryterra.co/unified-api/requesting-historical-data.md): backfill data from before a user connected.
* [Webhooks](https://docs.tryterra.co/destinations/webhooks.md): verify signatures, and see how timeouts and the circuit breaker work.
