> 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-docs/documentation/monitoring.md).

# Monitoring and debugging

## 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-docs/documentation/managing-orders.md#list-orders)).
* `webhooks.failed_total` > 0 means deliveries to your endpoint are failing - investigate below.

## Webhook delivery outcomes

`GET /api/v1/webhook-deliveries` lists the terminal outcome of every webhook delivery attempt against your endpoint, newest first (keyset-paginated):

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

```json
{
  "deliveries": [
    {
      "event_id": "333410942627700737",
      "event_type": "EVENT_TYPE_ORDER_ITEM_RESULTS_STATUS_CHANGED",
      "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": "EVENT_TYPE_ORDER_STATUS_CHANGED",
      "order_id": "333410942627700900",
      "order_item_id": "",
      "outcome": "dead_lettered",
      "final_status_code": 0,
      "attempts": 0,
      "completed_at": "2026-07-19T11:02:47Z",
      "event_created_at": "2026-07-19T10:20:11Z"
    }
  ]
}
```

| `outcome`       | Meaning                                                                  |
| --------------- | ------------------------------------------------------------------------ |
| `delivered`     | Your endpoint returned 2xx                                               |
| `rejected`      | Your endpoint returned a non-retryable 4xx - the event was not retried   |
| `invalid`       | No webhook URL was registered when the event fired                       |
| `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`.

`attempts` and `final_status_code` describe the delivery round that produced the outcome: for `delivered` and `rejected` they carry the HTTP attempt count and the final response code of that round. Dead-lettered records are written from the parked event after all retry rounds are exhausted and carry `attempts: 0` and `final_status_code: 0` - they are not a count of the total calls made (see [Webhooks](/vantage-api-docs/documentation/webhooks.md#delivery-and-retries) for the retry schedule).

{% hint style="info" %}
`event_type` here uses internal enum names (e.g. `EVENT_TYPE_ORDER_ITEM_RESULTS_STATUS_CHANGED`), not the `event_type` strings from the webhook payloads (`order_item.results_status_change`). Match deliveries to webhook payloads by `event_id`, not `event_type`.
{% endhint %}

## Debugging a missed webhook

1. **Check the delivery outcome** - `GET /api/v1/webhook-deliveries` filtered around the time window. `rejected` means your endpoint returned an error; `invalid` means the event was undeliverable (usually no URL registered); `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-docs/documentation/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.