> 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/vantage-api/monitoring.md).

# Monitoring and debugging

Observe your integration in production: the analytics overview endpoint, webhook events and their delivery attempts, delivery outcomes, and how to debug missed webhooks.

## Analytics overview

`GET /api/v1/overview` returns a summary of your account's activity for a time window (default: the last 7 days):

```bash
curl 'https://vantage.tryterra.co/api/v1/overview?since=2026-07-01T00:00:00Z' \
  -u 'YOUR_DEV_ID:YOUR_API_KEY'
```

```json
{
  "orders": {
    "total": 37,
    "by_status": {
      "order.completed": 29,
      "order.processing": 8
    }
  },
  "results": {
    "total": 25,
    "missing": 4
  },
  "webhooks": {
    "failed_total": 2,
    "daily": [
      { "date": "2026-07-18", "failed": 1 },
      { "date": "2026-07-19", "failed": 1 }
    ]
  }
}
```

* `orders.by_status` is keyed by the current `order.*` fulfilment status.
* `results.missing` counts delivered/completed orders still waiting on results - drill into them with `GET /api/v1/orders?missing=true` ([Managing orders](/vantage-api/managing-orders.md#list-orders)).
* `webhooks.failed_total` > 0 means deliveries to your endpoint are failing - investigate below.

## Webhook events and delivery attempts

Every webhook event is recorded the moment it happens, with a delivery status and a record of each HTTP attempt to your endpoint. In the dashboard, **Vantage → Event log** lists your events, including ones Terra has not delivered yet:

| Status      | Meaning                                                                                                     |
| ----------- | ----------------------------------------------------------------------------------------------------------- |
| `pending`   | Not delivered yet: no attempt has been made, or the last one failed and Terra will retry at the time shown  |
| `delivered` | Your endpoint returned 2xx                                                                                  |
| `failed`    | Terra stopped trying: a response it does not retry, a URL that can never be delivered to, or the last retry |
| `canceled`  | Never sent, for example because no webhook URL or signing secret was set; the event says why                |

Open an event to see its payload and every attempt: when it was made, the URL, the status code your endpoint returned (or why there was none, such as `host_not_found` or `connection_failed`) and how long it took. To send a delivered event again, use `POST /api/v1/webhook-events/resend`. You can also ask your AI assistant, for example "Which Vantage webhooks failed this week, and why?" - see [Use Vantage from your AI assistant](/vantage-api/overview.md#use-vantage-from-your-ai-assistant).

## Webhook delivery outcomes

`GET /api/v1/webhook-deliveries` lists the outcome of every event whose delivery has finished, newest first (keyset-paginated). Events still being retried are not listed until they finish.

```bash
curl 'https://vantage.tryterra.co/api/v1/webhook-deliveries?outcome=failed' \
  -u 'YOUR_DEV_ID:YOUR_API_KEY'
```

```json
{
  "data": [
    {
      "event_id": "333410942627700737",
      "event_type": "order_item.results_status_change",
      "order_id": "333410942627700736",
      "order_item_id": "333410942627700737",
      "outcome": "rejected",
      "final_status_code": 401,
      "attempts": 1,
      "completed_at": "2026-07-19T10:41:22Z",
      "event_created_at": "2026-07-19T10:39:03Z"
    },
    {
      "event_id": "333410942627700912",
      "event_type": "order.status_changed",
      "order_id": "333410942627700900",
      "order_item_id": "",
      "outcome": "dead_lettered",
      "final_status_code": null,
      "attempts": 14,
      "completed_at": "2026-07-19T11:02:47Z",
      "event_created_at": "2026-07-19T10:20:11Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

| `outcome`       | Meaning                                                                                            |
| --------------- | -------------------------------------------------------------------------------------------------- |
| `delivered`     | Your endpoint returned 2xx                                                                         |
| `rejected`      | Your endpoint returned a non-retryable 4xx - the event was not retried                             |
| `invalid`       | The webhook URL can never be delivered to, for example because it is not a valid http or https URL |
| `dead_lettered` | All retries exhausted - the event is parked and can be replayed by Terra                           |
| `replayed`      | A previously failed event was re-delivered                                                         |

Filter with `outcome=<value>`, or `outcome=failed` as a shorthand for `rejected|invalid|dead_lettered`.

* `event_type` uses the same strings as the webhook payloads (`order.status_changed`, `order_item.results_status_change`).
* `attempts` counts every HTTP attempt made for the event, across all retries.
* `final_status_code` is the status code your endpoint returned to the last attempt, or `null` when that attempt got no HTTP response (a DNS failure, refused connection or timeout).

## Debugging a missed webhook

1. **Check the event in the dashboard** - Vantage → Event log shows whether it is still `pending` and what each attempt got back. `GET /api/v1/webhook-deliveries` lists finished deliveries. `rejected` means your endpoint returned an error; `invalid` means the registered URL can never be delivered to; `dead_lettered` means your endpoint was unreachable through all retries.
2. **Cross-check current state via REST** - `GET /api/v1/orders/{orderID}` shows the authoritative `status_history` regardless of what was delivered.
3. **Verify your registered URL** - `GET /api/v1/clients/webhook-url` for the environment in question (sandbox and production hold separate URLs).
4. **Check your signature verification** - a verifier that rejects valid signatures shows up as `rejected` with a `final_status_code` of 401. Common causes: verifying against a re-serialized body instead of the raw bytes, or treating the timestamp as milliseconds (it is Unix **seconds**). See [Webhooks](/vantage-api/webhooks.md#signature-verification).
5. **Contact support with the `event_id`** (or the `X-Terra-Trace-Id` header value from a delivery) - it uniquely identifies the delivery for Terra's team, and dead-lettered events can be replayed.
