Webhooks

• a commercial decision is made: accepted, rejected, or duplicate_not_accepted;
• billing moves from pending to billable or not_billable;
• a lead is returned (Lead Return);
• an enrolled document-first submission’s handoff link becomes available.

​

Set up an endpoint

• One endpoint per environment. Sandbox and production are configured, signed, and delivered separately.
• The URL must use https, resolve to a public host, and be at most 2048 characters. Tera rejects localhost, .local / .internal host names, private and loopback IP addresses, credentials in the URL, and #fragments.
• When the endpoint is created, Tera generates a signing secret that starts with whsec_. It is shown once. Store it in your secret manager. Tera cannot show it again.
• Tera staff can send a test event for one of your existing submissions in that environment. A test event is a normal submission.status_changed event carrying that submission’s current status.

​

Request

​

Event envelope

{
  "id": "33333333-3333-4333-8333-333333333333",
  "type": "submission.status_changed",
  "occurred_at": "2026-08-29T14:40:00.000Z",
  "data": {
    "environment": "production",
    "submission_id": "22222222-2222-4222-8222-222222222222",
    "external_reference": "harbourview-enq-2001",
    "level": "application",
    "status": "returned",
    "received_at": "2026-08-29T10:15:02.000Z",
    "decided_at": "2026-08-29T14:40:00.000Z",
    "application_reference": "TBF-7K2M9QXA",
    "application_created_at": "2026-08-29T10:15:09.000Z",
    "billing": {
      "billing_status": "not_billable",
      "billable_at": null,
      "billing_model": "pre_underwriting_cleared",
      "not_billable_reason": "returned"
    },
    "return": {
      "reason_category": "outstanding_ccjs",
      "reason_category_version": "v1",
      "returned_at": "2026-08-29T14:40:00.000Z"
    }
  }
}

​

Verify the signature

import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCE_SECONDS = 300;

export function verifyTeraWebhook({ secret, rawBody, timestamp, signatureHeader }) {
  if (!signatureHeader || !/^\d{1,12}$/.test(timestamp ?? "")) return false;
  const nowSeconds = Math.floor(Date.now() / 1000);
  if (Math.abs(nowSeconds - Number(timestamp)) > TOLERANCE_SECONDS) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`, "utf8")
    .digest();

  return signatureHeader
    .split(",")
    .map((entry) => entry.trim())
    .filter((entry) => entry.startsWith("v1="))
    .some((entry) => {
      const provided = Buffer.from(entry.slice(3), "hex");
      return provided.length === expected.length && timingSafeEqual(provided, expected);
    });
}

import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300


def verify_tera_webhook(secret: str, raw_body: bytes, timestamp: str, signature_header: str) -> bool:
    if not signature_header or not timestamp or not timestamp.isdigit():
        return False
    if abs(int(time.time()) - int(timestamp)) > TOLERANCE_SECONDS:
        return False

    signed = timestamp.encode("utf-8") + b"." + raw_body
    expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()

    for entry in signature_header.split(","):
        entry = entry.strip()
        if entry.startswith("v1=") and hmac.compare_digest(entry[3:], expected):
            return True
    return False

​

Respond

• Return any 2xx status within 10 seconds. The response body is ignored.
• Do the work after you respond. Store the event, return 2xx, then process it from your own queue.
• Any other status, a timeout, or a network error counts as a failed attempt.
• Tera does not follow redirects. A 3xx response is a failed attempt. Configure the final URL.
• Return 2xx for a duplicate event you have already processed.

​

Retries

​

Idempotency and ordering

• Deduplicate on id (or Tera-Webhook-Id). Every retry of an event carries the same id. Process each id once.
• Events can arrive out of order. A retried older event can arrive after a newer one. Each event carries the full status object, so keep the event with the latest occurred_at per submission_id and ignore older ones.
• Match on your reference. data.external_reference and data.submission_id identify the submission. The envelope does not repeat them.

​

Rotate the signing secret

​

Status reads still work

• recover after a delivery fails or your endpoint is down;
• reconcile your records on a schedule;
• read a fresh handoff.customer_journey_url for an enrolled document-first submission.