Best practices

Patterns that keep a Vantage integration robust: webhook handling, deduplication, safe retries, ID handling, and result delivery done right.

Webhook handling

• Verify the signature on every delivery before parsing the body (Webhooks). Use the raw request bytes and remember the timestamp is Unix seconds.

• Return 2xx fast. Persist the event and process asynchronously; Terra times out deliveries after 10 seconds and treats non-2xx as failure.

• Deduplicate on event_id. Delivery is at-least-once; you will occasionally see the same event twice.

• Don't assume ordering. A delivery can be stale by the time it arrives - never let an older status overwrite a newer one you've already recorded. When you must establish the authoritative current state, read status_history from GET /api/v1/orders/{orderID}.

• Reconcile periodically. A daily sweep of GET /api/v1/orders?missing=true (delivered orders still waiting on results) and GET /api/v1/results?status=results.results_ready (ready but perhaps unacknowledged) catches anything a missed webhook would otherwise hide.

Placing orders

• Generate a unique client_order_reference_id per order and store the mapping to order_id. It is your reconciliation key across webhooks, REST reads, and support requests.

• Send an Idempotency-Key on order creation. A unique key per order attempt makes retries safe: the same key + same body replays the original result instead of double-ordering (and double-charging). Keep client_order_reference_id as your reconciliation key - it is not a dedupe key. If you can't send the header, don't blind-retry ambiguous failures (timeout, 5xx): first list recent orders (GET /api/v1/orders?since=...) and check whether your client_order_reference_id already appears.

• Check available_collection_types on the variant before offering AT_HOME vs GO_TO_LAB to a user, and send the matching address field (shipping_address vs requested_lab_address).

• Validate phone numbers with their country code client-side; the API rejects mismatches with a field-level validation error (Errors).

Handling identifiers

• Store all Vantage IDs as strings. order_id, order_item_id, recipient_id, test_taker_id are 64-bit values serialized as JSON strings; parsing them as doubles (JavaScript's default for numbers) corrupts them.

• Key your results flow on order_item_id, not order_id - activation, result statuses, downloads, and acknowledgment are all per item.

• Capture test_taker_id when it first appears (the results.kit_activated webhook, or any later result webhook). You need it to fetch and acknowledge results. If you miss it, recover it from GET /api/v1/orders/{orderID} under items[].test_taker_ids.

Delivering results to your users

• Re-mint download URLs on demand. The presigned download_url expires after 15 minutes - fetch it when the user opens the result, never store it.

• Make acknowledgment an explicit user action. Call the acknowledge endpoint when the user has actually viewed their results - a button or checkbox - never automatically on retrieval. This is a compliance requirement, not a technicality (Acknowledging Results).

• Treat escalations as urgent. On results.escalation_raised, surface the result to the user promptly and acknowledge before acknowledgment_due_by; unacknowledged escalations can trigger direct outreach to the patient by medical teams.

• Handle the failure paths. Build product flows for results.sample_rejected (offer a replacement kit) and results.lab_processing_error - they happen in production.

Environments

• Build against sandbox first; it delivers the same signed webhooks as production. Use the simulate endpoint in automated tests - it is deterministic and covers failure paths.

• Remember sandbox and production hold separate webhook URLs, and supplier_item_id appears in sandbox webhook payloads only.

• Before launch, walk the Going to production checklist.