Webhooks

How Vantage API delivers order and result updates to your endpoint: event families and payloads, HMAC signature verification, and retry semantics.

Overview

Webhooks are how Vantage API keeps you connected to the kit throughout the fulfilment and results process. Every state change is delivered as a signed HTTP POST to the HTTPS endpoint you registered (Account setup).

There are two event families, distinguished by the event_type field:

event_type	Scope	What it carries
order.status_changed	Order	Fulfilment progress: a status in the same order.* vocabulary REST uses, plus tracking_number once available
order_item.results_status_change	Order item	Results progress: a results_status in the results.* vocabulary, plus the test_taker

event_type tells you which family the event belongs to; the status / results_status field inside data tells you which state was reached. Route on event_type, then switch on the status field.

Every payload has the same envelope:

{
  "event_type": "order.status_changed",
  "event_id": "249956485092777984",
  "timestamp": 1763661470,
  "data": { }
}

• event_id - unique per event, serialized as a JSON string (like all Vantage IDs). Delivery is at-least-once: deduplicate on event_id. It equals the X-Terra-Trace-Id header.

• timestamp - Unix seconds when the event was sent.

Headers

Header	Description	Example
X-Terra-Signature	HMAC signature with timestamp	t=1763661470,v1=a1b2c3...
X-Terra-Trace-Id	Unique ID for debugging (matches the event_id)	249956485092777984
Content-Type	Always application/json	application/json

Signature verification

Webhooks are signed with HMAC-SHA256 using your Terra signing secret (the same signing secret shown in your Terra dashboard). Verify every delivery before trusting it.

The X-Terra-Signature header has the format:

t=<unix_timestamp_seconds>,v1=<hex_signature>

• t - Unix timestamp in seconds when the webhook was sent

• v1 - hex-encoded HMAC-SHA256(signing_secret, "<t>.<raw_body>")

Verification steps:

1. Parse t and v1 from the header.

2. Reject if t is outside your tolerance window of now (5 minutes is a sensible default).

3. Concatenate <t> + . + the raw, unaltered request body.

4. Compute HMAC-SHA256 over that string with your signing secret.

5. Compare to v1 with a constant-time comparison.

Python

import hashlib
import hmac
import time

from flask import Flask, abort, request

app = Flask(__name__)

SIGNING_SECRET = "your_signing_secret_here"
TIMESTAMP_TOLERANCE = 300  # 5 minutes, in seconds


def verify_webhook(request):
    signature_header = request.headers.get("X-Terra-Signature")
    if not signature_header:
        return False, "Missing signature header"

    try:
        parts = dict(
            item.split("=", 1)
            for item in signature_header.split(",")
            if "=" in item
        )
        timestamp = int(parts["t"])
        received_signature = parts["v1"]
    except (KeyError, ValueError):
        return False, "Invalid signature format"

    if abs(int(time.time()) - timestamp) > TIMESTAMP_TOLERANCE:
        return False, "Timestamp too old or in future"

    body = request.get_data(as_text=True)
    signed_string = f"{timestamp}.{body}"

    expected_signature = hmac.new(
        SIGNING_SECRET.encode("utf-8"),
        signed_string.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(expected_signature, received_signature):
        return False, "Signature mismatch"

    return True, None


@app.route("/webhooks/terra", methods=["POST"])
def webhook_handler():
    valid, error = verify_webhook(request)
    if not valid:
        abort(401, description=error)

    data = request.get_json()
    print(f"Received webhook: {data}")

    return "", 200


if __name__ == "__main__":
    app.run(port=3000)

Go

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"crypto/subtle"
	"encoding/hex"
	"fmt"
	"io"
	"net/http"
	"os"
	"strconv"
	"strings"
	"time"
)

const timestampTolerance = 300 // 5 minutes, in seconds

func VerifyWebhook(r *http.Request, signingSecret string) (bool, error) {
	bodyBytes, err := io.ReadAll(r.Body)
	if err != nil {
		return false, fmt.Errorf("failed to read body: %w", err)
	}
	defer r.Body.Close()

	signatureHeader := r.Header.Get("X-Terra-Signature")
	if signatureHeader == "" {
		return false, fmt.Errorf("missing X-Terra-Signature header")
	}

	var timestamp int64
	var receivedSig string
	for _, part := range strings.Split(signatureHeader, ",") {
		keyValue := strings.SplitN(part, "=", 2)
		if len(keyValue) != 2 {
			continue
		}
		switch keyValue[0] {
		case "t":
			timestamp, err = strconv.ParseInt(keyValue[1], 10, 64)
			if err != nil {
				return false, fmt.Errorf("invalid timestamp: %w", err)
			}
		case "v1":
			receivedSig = keyValue[1]
		}
	}

	age := time.Now().Unix() - timestamp
	if age > timestampTolerance || age < -timestampTolerance {
		return false, fmt.Errorf("timestamp too old or in future")
	}

	signedString := fmt.Sprintf("%d.%s", timestamp, string(bodyBytes))

	mac := hmac.New(sha256.New, []byte(signingSecret))
	mac.Write([]byte(signedString))
	expectedSig := hex.EncodeToString(mac.Sum(nil))

	if subtle.ConstantTimeCompare([]byte(expectedSig), []byte(receivedSig)) != 1 {
		return false, fmt.Errorf("signature mismatch")
	}
	return true, nil
}

func WebhookHandler(w http.ResponseWriter, r *http.Request) {
	signingSecret := os.Getenv("TERRA_SIGNING_SECRET")

	valid, err := VerifyWebhook(r, signingSecret)
	if err != nil || !valid {
		http.Error(w, "Invalid signature", http.StatusUnauthorized)
		return
	}

	w.WriteHeader(http.StatusOK)
}

Compute the HMAC over the raw request body bytes, before any JSON parsing or re-serialization - re-encoding the JSON can reorder keys and change whitespace, which breaks the signature.

Delivery and retries

• Respond with any 2xx status quickly (within 10 seconds); do heavy processing asynchronously.

• On failure (network error, timeout, 408, 429, or any 5xx), the first delivery makes up to 5 HTTP attempts with exponential backoff and jitter (roughly 1s, 2s, 4s, 8s). If they all fail, the event is re-queued and redelivered as single attempts with growing delays (starting at 5s, doubling up to a 10-minute cap), up to 10 deliveries in total - at most ~14 calls spread over ~30 minutes - before the event is parked. Make your handler idempotent either way. Other 4xx responses are treated as a rejection and are not retried.

• Parked (dead-lettered) events can be replayed by Terra - they are not silently lost.

• Delivery is at-least-once and ordering is not guaranteed: deduplicate on event_id, and treat each event's status as the authoritative current state rather than assuming you saw every intermediate step.

You can inspect delivery outcomes (delivered, rejected, dead-lettered, attempt counts, final status codes) via GET /api/v1/webhook-deliveries - see Monitoring and debugging.

Event reference

order.status_changed

data fields: order_id (string), status, plus tracking_number and (sandbox only) supplier_item_id once available.

status	Meaning
order.payment_processing	Payment being processed (initial state of payment-gated orders; appears in the order response rather than as a webhook)
order.payment_complete	Payment confirmed
order.payment_failed	Payment failed
order.processing	Order accepted and being prepared by the supplier
order.delayed	Fulfilment delayed
order.delivery_fulfilled	Delivery details available - carries tracking_number
order.completed	Order complete
order.cancelled	Order cancelled

Example:

{
  "event_type": "order.status_changed",
  "event_id": "249956485092777984",
  "timestamp": 1763661470,
  "data": {
    "order_id": "251285377984405504",
    "status": "order.delivery_fulfilled",
    "tracking_number": "KnD3d5PMZyq5ulNcWkrq"
  }
}

REST reads of the same order use the identical vocabulary - a webhook status can be matched verbatim against order_status or status_history.

order_item.results_status_change

data fields: order_id, order_item_id, variant_id (all strings), results_status, and a test_taker object (test_taker_id string, first_name, last_name, email, phone_number E.164 string). Depending on the status, also: failure_cause, escalation_level, acknowledgment_due_by.

results_status	Meaning	Extra fields
results.kit_activated	End user activated their kit (suppliers with an activation step only)	-
results.sample_processing_in_lab	Lab confirmed receipt of the sample	-
results.partial_results_ready	A subset of the panel has resulted	-
results.results_ready	Results available - fetch and acknowledge	-
results.sample_rejected	Lab rejected the sample	failure_cause (e.g. "blood contaminated")
results.lab_processing_error	Lab could not process the sample	-
results.escalation_raised	Clinical escalation on the result set	escalation_level, acknowledgment_due_by

(results.awaiting_sample is the initial per-item state set at order creation; it appears in the order response rather than as a webhook.)

Example - results ready:

{
  "event_type": "order_item.results_status_change",
  "event_id": "249958796259139584",
  "timestamp": 1763662021,
  "data": {
    "order_id": "251285377984405504",
    "order_item_id": "251285377984405507",
    "variant_id": "100041",
    "results_status": "results.results_ready",
    "test_taker": {
      "test_taker_id": "257837964552478720",
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone_number": "[phone]"
    }
  }
}

Example - escalation raised:

{
  "event_type": "order_item.results_status_change",
  "event_id": "252476147693166592",
  "timestamp": 1764262204,
  "data": {
    "order_id": "251285377984405504",
    "order_item_id": "251285377984405507",
    "variant_id": "100041",
    "results_status": "results.escalation_raised",
    "escalation_level": "medium",
    "acknowledgment_due_by": "2026-07-24T16:04:01Z",
    "test_taker": {
      "test_taker_id": "257837964552478720",
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone_number": "[phone]"
    }
  }
}

escalation_level is one of not_escalated, very_low, low, medium, high, very_high. Escalations require prompt acknowledgment - see Acknowledging Results.