Webhooks

Status polling is a fallback for resync or recovery only — not a real-time channel.

​

Event envelope

{
  "id": "33333333-3333-4333-8333-333333333333",
  "type": "submission.status_changed",
  "occurred_at": "2026-08-29T14:40:00.000Z",
  "data": {
    "submission_id": "22222222-2222-4222-8222-222222222222",
    "external_reference": "your-ref-123",
    "status": "returned",
    "billing_model": "pre_underwriting_cleared",
    "...": "full SupplierVisibleStatus object"
  }
}

​

Headers

​

Verify signatures

1. Retrieve your Webhook Secret from your supplier settings (format: whsec_...).
2. Extract the Tera-Webhook-Timestamp and Tera-Webhook-Signature headers from the incoming request.
3. Compute the signed payload:
   <timestamp>.<body_bytes>
   
   where body_bytes is the raw request body (not parsed JSON).
4. Sign with HMAC-SHA256 using your secret as the key:
   hex_signature = hmac_sha256("<timestamp>.<body_bytes>", secret_key)
   
5. Compare the computed signature with the one in the header (after the v1= prefix). If they match, the webhook is authentic.
6. Check that Tera-Webhook-Timestamp is within the last 300 seconds to reject replay attacks.

​

Example verification (Node.js)

import crypto from "crypto";

function verifyWebhookSignature(
  body,
  timestamp,
  signature,
  secret
) {
  const payload = `${timestamp}.${body}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

​

Response handling

• Returns any 2xx status: delivery is considered successful
• Returns 3xx, 4xx, or 5xx: delivery fails and will retry
• Times out (>10 seconds): delivery fails and will retry
• Redirects: redirects are not followed; treat 3xx as failed

​

Event lifecycle

1. Event created — submission status changes in Pre-Underwriting or shortly after.
2. Tera sends webhook — POST to your endpoint with signature.
3. Your endpoint responds — any 2xx is treated as success.
4. Delivery completes — or enters retry loop on failure.

​

See also

• Webhooks guide — detailed setup and best practices.
• Lead Return guide — handling status: "returned" and Return Reason Categories.
• Status polling — recovery and resync strategies.