Monitoring and debugging

Observe your integration in production: the analytics overview endpoint, webhook 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):

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

{
  "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).

• 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):

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

{
  "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 for the retry schedule).

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.

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.

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.