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

# Webhooks

The webhook events Vantage sends, and the calls that resend an event or send a test one.

## Resend a webhook event

> Sends a delivered webhook event again to your current webhook URL, signed with your current signing secret and rendered in your pinned version.\
> \
> \- The payload is rebuilt from the stored event: it carries the status the event originally announced, not the order's current status, and a fresh \`timestamp\`.\
> \- The event keeps its \`event\_id\`, so an endpoint that dedupes on it treats the resend as the event it already processed.\
> \- Delivery is asynchronous: 202 means queued, not arrived. Find the outcome with \`GET /api/v1/webhook-deliveries\`, where the resend replaces the event's earlier outcome.\
> \- An event can be resent for 30 days after delivery. An older one, or one delivered before Vantage began keeping delivered events, returns 404 with code \`event\_not\_resendable\`.

```json
{"openapi":"3.2.0","info":{"title":"Terra Vantage API","version":"2026.11.11.1"},"tags":[{"name":"webhooks","summary":"Webhooks","description":"The webhook events Vantage sends, and the calls that resend an event or send a test one."}],"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]},{"DataBearer":[],"DevIDHeader":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic","description":"Authenticate with your Terra API credentials: username = your Terra\n`dev-id`, password = your Terra API key — the same credentials used for\nevery other Terra API. The header pair `dev-id` + `x-api-key` is also\naccepted. Suspended credentials receive 403; accounts without the\nVantage entitlement receive 403 once entitlement enforcement is\nenabled. Once the credential validator is configured, backfilled keys\nalso honor current token expiry, revocation, audience and Vantage scopes.\nInvalid tokens receive 401, insufficient scopes 403 and an unavailable\nvalidator 503. These checks remain active when product policy is off.\n"},"DataBearer":{"type":"http","scheme":"bearer","bearerFormat":"Terra data token","description":"A data-plane token with vantage:read for reads or vantage:write for writes. Requires dev-id. Write includes read; data:read alone does not grant Vantage. Available after the API credential validator is configured."},"DevIDHeader":{"type":"apiKey","in":"header","name":"dev-id","description":"Environment owned by the data token's customer and within its audience."}},"parameters":{"ApiVersion":{"name":"X-Terra-Version","in":"header","required":false,"description":"The API version to serve this request in. Defaults to your account's pinned version; an account is pinned to the latest version on its first request.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15","2026-10-29"]}},"DryRun":{"name":"dry_run","in":"query","required":false,"description":"When true, runs every check and returns what the operation would do, with 200, without doing it. Defaults to false.","schema":{"type":"boolean","default":false}}},"schemas":{"ResendWebhookEventRequest":{"type":"object","required":["event_id"],"properties":{"event_id":{"type":"string","description":"The `event_id` of the delivered webhook (also its `X-Terra-Trace-Id`)."},"event_type":{"type":"string","description":"Optional; when set it must match the stored event's type."}}},"ResendWebhookEventDryRunResponse":{"type":"object","required":["dry_run","would","preview"],"properties":{"dry_run":{"type":"boolean","const":true},"would":{"type":"string","const":"resend"},"preview":{"$ref":"#/components/schemas/ResendWebhookEventResponse"}}},"ResendWebhookEventResponse":{"type":"object","required":["event_id","event_type","dispatched"],"properties":{"event_id":{"type":"string"},"event_type":{"type":"string"},"dispatched":{"type":"boolean","description":"True when the event was queued; false in a dry-run preview."}}},"ProblemDetail":{"description":"Standard error response format following RFC 7807 specification","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}}},"Refusal":{"description":"A credential refusal from Terra's edge, served as `application/problem+json` in every version. The HTTP status is not repeated in the body.","type":"object","required":["type","title","instance","detail","code"],"properties":{"type":{"type":"string"},"title":{"type":"string","description":"The HTTP status text, lowercased."},"instance":{"type":"string","description":"The request path, with its query."},"detail":{"type":"string"},"code":{"type":"string","description":"Why the credential was refused: `unauthorized` (401) for a missing, invalid, expired or revoked credential; `scope_missing` (403) for one that lacks the scope this operation requires; `audience_restricted` (403) for one not granted for this dev-id; `authorization_unavailable` (503) when the credential could not be checked, so retry later.","enum":["unauthorized","scope_missing","audience_restricted","authorization_unavailable"]}}},"WebhookEventProblem":{"description":"RFC 7807 problem from the webhook-events operations, with a code to branch on and a remediation to show. (Flat rather than an allOf over ProblemDetail: the conformance gate seals declared objects.)","type":"object","required":["code","detail","status","title","type"],"properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"},"code":{"type":"string","enum":["not_found","event_not_resendable","webhook_url_missing"]},"remediation":{"type":"string"}}}},"headers":{"ApiVersion":{"description":"The API version this response was rendered in.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15","2026-10-29"]}},"RequestId":{"description":"A UUID generated for this request, unique per request and never taken from the caller. Quote it to support to find the request.","schema":{"type":"string","format":"uuid"}}}},"paths":{"/api/v1/webhook-events/resend":{"post":{"operationId":"resendWebhookEvent","summary":"Resend a webhook event","tags":["webhooks"],"description":"Sends a delivered webhook event again to your current webhook URL, signed with your current signing secret and rendered in your pinned version.\n\n- The payload is rebuilt from the stored event: it carries the status the event originally announced, not the order's current status, and a fresh `timestamp`.\n- The event keeps its `event_id`, so an endpoint that dedupes on it treats the resend as the event it already processed.\n- Delivery is asynchronous: 202 means queued, not arrived. Find the outcome with `GET /api/v1/webhook-deliveries`, where the resend replaces the event's earlier outcome.\n- An event can be resent for 30 days after delivery. An older one, or one delivered before Vantage began keeping delivered events, returns 404 with code `event_not_resendable`.","parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"$ref":"#/components/parameters/DryRun"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendWebhookEventRequest"}}}},"responses":{"200":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"`dry_run=true`: the event can be resent; nothing was queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendWebhookEventDryRunResponse"}}}},"202":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Queued for redelivery.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendWebhookEventResponse"}}}},"400":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Malformed body, an event_id that is not an event id, an event_type that does not match the stored event, or a dry_run that is not a boolean. An unsupported `X-Terra-Version` also returns 400 with code `invalid_api_version`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}},"403":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"The credential lacks the scope this operation requires (code `scope_missing`) or is not granted for this dev-id (code `audience_restricted`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}},"404":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"No event with that event_id was sent to you (code `not_found`), or it cannot be resent (code `event_not_resendable`); `remediation` says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEventProblem"}}}},"422":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"No webhook URL is configured (code `webhook_url_missing`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEventProblem"}}}},"500":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Current authorization is unavailable; retry after the dependency recovers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}}}}}}}
```

## Send a test webhook event

> Sends a generated event of one webhook type to your current webhook URL, through the same delivery as real events: signed with \`X-Terra-Signature\`, rendered in your pinned version and retried the same way.\
> \
> \- It carries \`"test": true\` and describes no real order: every order, order item, variant and test-taker id in it is \`"0"\`, and the test taker is a placeholder.\
> \- It changes no order or result.\
> \- Under selected product enforcement, it is delivered only while the environment has a current Vantage grant.\
> \- The response carries the payload in the latest version's shape; the delivery is stamped with its own \`timestamp\` when sent.

```json
{"openapi":"3.2.0","info":{"title":"Terra Vantage API","version":"2026.11.11.1"},"tags":[{"name":"webhooks","summary":"Webhooks","description":"The webhook events Vantage sends, and the calls that resend an event or send a test one."}],"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]},{"DataBearer":[],"DevIDHeader":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic","description":"Authenticate with your Terra API credentials: username = your Terra\n`dev-id`, password = your Terra API key — the same credentials used for\nevery other Terra API. The header pair `dev-id` + `x-api-key` is also\naccepted. Suspended credentials receive 403; accounts without the\nVantage entitlement receive 403 once entitlement enforcement is\nenabled. Once the credential validator is configured, backfilled keys\nalso honor current token expiry, revocation, audience and Vantage scopes.\nInvalid tokens receive 401, insufficient scopes 403 and an unavailable\nvalidator 503. These checks remain active when product policy is off.\n"},"DataBearer":{"type":"http","scheme":"bearer","bearerFormat":"Terra data token","description":"A data-plane token with vantage:read for reads or vantage:write for writes. Requires dev-id. Write includes read; data:read alone does not grant Vantage. Available after the API credential validator is configured."},"DevIDHeader":{"type":"apiKey","in":"header","name":"dev-id","description":"Environment owned by the data token's customer and within its audience."}},"parameters":{"ApiVersion":{"name":"X-Terra-Version","in":"header","required":false,"description":"The API version to serve this request in. Defaults to your account's pinned version; an account is pinned to the latest version on its first request.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15","2026-10-29"]}},"DryRun":{"name":"dry_run","in":"query","required":false,"description":"When true, runs every check and returns what the operation would do, with 200, without doing it. Defaults to false.","schema":{"type":"boolean","default":false}}},"schemas":{"GenerateWebhookEventRequest":{"type":"object","required":["event_type"],"properties":{"event_type":{"type":"string","enum":["order.status_changed","order_item.results_status_change"]},"status":{"type":"string","description":"The `data.status` (for order.status_changed) or `data.results_status` (for order_item.results_status_change) the event carries, from that webhook's enum. Defaults to `order.delivery_fulfilled` and `results.results_ready`."}}},"GenerateWebhookEventDryRunResponse":{"type":"object","required":["dry_run","would","preview"],"properties":{"dry_run":{"type":"boolean","const":true},"would":{"type":"string","const":"dispatch"},"preview":{"$ref":"#/components/schemas/GenerateWebhookEventResponse"}}},"GenerateWebhookEventResponse":{"type":"object","required":["event_id","event_type","dispatched","payload"],"properties":{"event_id":{"type":"string"},"event_type":{"type":"string"},"dispatched":{"type":"boolean","description":"True when the event was queued; false in a dry-run preview."},"payload":{"description":"The latest-shape webhook body.","oneOf":[{"$ref":"#/components/schemas/OrderStatusChangedEvent"},{"$ref":"#/components/schemas/OrderItemResultsStatusChangedEvent"}]}}},"OrderStatusChangedEvent":{"type":"object","required":["event_type","event_id","timestamp","data"],"properties":{"event_type":{"type":"string","const":"order.status_changed"},"event_id":{"type":"string","description":"Unique per event (64-bit id serialized as a string) — deduplicate on this. Equals the X-Terra-Trace-Id header."},"timestamp":{"type":"integer","description":"Unix seconds when the event was sent."},"test":{"type":"boolean","const":true,"description":"Present only on events from `POST /api/v1/webhook-events/generate`, which describe no real order."},"data":{"type":"object","required":["order_id","status"],"properties":{"order_id":{"type":"string"},"status":{"type":"string","enum":["order.payment_processing","order.payment_complete","order.payment_failed","order.processing","order.delayed","order.cancelled","order.completed","order.delivery_fulfilled"]},"tracking_number":{"type":"string","description":"Present once delivery details are available."},"supplier_item_id":{"type":"string","description":"Sandbox payloads only — the supplier-side kit ID."}}}}},"OrderItemResultsStatusChangedEvent":{"type":"object","required":["event_type","event_id","timestamp","data"],"properties":{"event_type":{"type":"string","const":"order_item.results_status_change"},"event_id":{"type":"string","description":"Unique per event (64-bit id serialized as a string) — deduplicate on this. Equals the X-Terra-Trace-Id header."},"timestamp":{"type":"integer","description":"Unix seconds when the event was sent."},"test":{"type":"boolean","const":true,"description":"Present only on events from `POST /api/v1/webhook-events/generate`, which describe no real order."},"data":{"type":"object","required":["order_id","order_item_id","variant_id","results_status","test_taker"],"properties":{"order_id":{"type":"string"},"order_item_id":{"type":"string"},"variant_id":{"type":"string"},"results_status":{"type":"string","enum":["results.kit_activated","results.sample_processing_in_lab","results.sample_rejected","results.partial_results_ready","results.results_ready","results.lab_processing_error","results.escalation_raised","results.genome_processing","results.sample_reanalysis","results.reanalysed"],"description":"Non-exhaustive: new statuses may be added without a new API version, so treat an unknown value as an in-progress state. `genome_processing`, `sample_reanalysis` and `reanalysed` are DNA-only."},"test_taker":{"type":"object","required":["test_taker_id","first_name","last_name","email","phone_number"],"properties":{"test_taker_id":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string"},"phone_number":{"type":"string","description":"E.164 phone number"}}},"escalation_level":{"type":"string","description":"Present on escalation_raised.","enum":["not_escalated","very_low","low","medium","high","very_high"]},"acknowledgment_due_by":{"type":"string","description":"Present on escalation_raised — ISO 8601 deadline."},"failure_cause":{"type":"string","description":"Present on sample_rejected."},"result_version":{"type":"integer","format":"int32","minimum":1,"description":"Present on results_ready and reanalysed: the version of the result now served, 1 for the first result and bumped by every re-analysis. Fetch the result again when it changes."},"amended":{"type":"boolean","const":true,"description":"Present only on results_ready for a later corrected release of a result already delivered; fetch the result again."}}}}},"ProblemDetail":{"description":"Standard error response format following RFC 7807 specification","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}}},"Refusal":{"description":"A credential refusal from Terra's edge, served as `application/problem+json` in every version. The HTTP status is not repeated in the body.","type":"object","required":["type","title","instance","detail","code"],"properties":{"type":{"type":"string"},"title":{"type":"string","description":"The HTTP status text, lowercased."},"instance":{"type":"string","description":"The request path, with its query."},"detail":{"type":"string"},"code":{"type":"string","description":"Why the credential was refused: `unauthorized` (401) for a missing, invalid, expired or revoked credential; `scope_missing` (403) for one that lacks the scope this operation requires; `audience_restricted` (403) for one not granted for this dev-id; `authorization_unavailable` (503) when the credential could not be checked, so retry later.","enum":["unauthorized","scope_missing","audience_restricted","authorization_unavailable"]}}},"WebhookEventProblem":{"description":"RFC 7807 problem from the webhook-events operations, with a code to branch on and a remediation to show. (Flat rather than an allOf over ProblemDetail: the conformance gate seals declared objects.)","type":"object","required":["code","detail","status","title","type"],"properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"},"code":{"type":"string","enum":["not_found","event_not_resendable","webhook_url_missing"]},"remediation":{"type":"string"}}}},"headers":{"ApiVersion":{"description":"The API version this response was rendered in.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15","2026-10-29"]}},"RequestId":{"description":"A UUID generated for this request, unique per request and never taken from the caller. Quote it to support to find the request.","schema":{"type":"string","format":"uuid"}}}},"paths":{"/api/v1/webhook-events/generate":{"post":{"operationId":"generateWebhookEvent","summary":"Send a test webhook event","tags":["webhooks"],"description":"Sends a generated event of one webhook type to your current webhook URL, through the same delivery as real events: signed with `X-Terra-Signature`, rendered in your pinned version and retried the same way.\n\n- It carries `\"test\": true` and describes no real order: every order, order item, variant and test-taker id in it is `\"0\"`, and the test taker is a placeholder.\n- It changes no order or result.\n- Under selected product enforcement, it is delivered only while the environment has a current Vantage grant.\n- The response carries the payload in the latest version's shape; the delivery is stamped with its own `timestamp` when sent.","parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"$ref":"#/components/parameters/DryRun"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateWebhookEventRequest"}}}},"responses":{"200":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"`dry_run=true`: the payload that would be sent; nothing was queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateWebhookEventDryRunResponse"}}}},"202":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Queued for delivery.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateWebhookEventResponse"}}}},"400":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Malformed body, an unknown event_type, a status that event type does not carry, or a dry_run that is not a boolean. An unsupported `X-Terra-Version` also returns 400 with code `invalid_api_version`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}},"403":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"The credential lacks the scope this operation requires (code `scope_missing`) or is not granted for this dev-id (code `audience_restricted`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}},"422":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"No webhook URL is configured (code `webhook_url_missing`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEventProblem"}}}},"500":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Current authorization is unavailable; retry after the dependency recovers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}}}}}}}
```

{% openapi-webhook spec="diagnostics" name="order.status\_changed" method="post" %}
[diagnostics](https://raw.githubusercontent.com/tryterra/openapi/master/dist/vantage/vantage-bundled.yaml)
{% endopenapi-webhook %}

{% openapi-webhook spec="diagnostics" name="order\_item.results\_status\_change" method="post" %}
[diagnostics](https://raw.githubusercontent.com/tryterra/openapi/master/dist/vantage/vantage-bundled.yaml)
{% endopenapi-webhook %}
