Webhooks

​

Set up your endpoint

1. Create an HTTPS endpoint on your server that accepts POST requests.
2. Email [email protected] with its URL and your partner name.
3. We’ll send you a signing secret, starting with whsec_. You’ll only receive it once, so store it as carefully as an API key.

​

What Tern sends

POST /tern/webhook HTTP/1.1
content-type: application/json
tern-event: quote.updated
tern-delivery: 48213
tern-signature: t=1793085912,v1=5f1c0e…

{"id":"q_01JB8Z5W3F6V9Q2X4K7M1N0P8R","status":"in_progress","source":{…},"destination":{…}}

​

Handle a request

1. Check the signature, as shown below. If it doesn’t match, reject the request.
2. Respond with any 2xx status within 10 seconds.
3. Do any slow work after responding, or add it to a queue. Requests that take too long are retried.

​

Check the signature

1. Split it on , and read t and v1.
2. Join t, a ., and the raw request body exactly as you received it, before parsing the JSON.
3. Compute the HMAC-SHA256 of that string using your signing secret, as lowercase hex.
4. Compare it with v1 using a constant-time comparison. Reject the request if they differ, or if t is more than 5 minutes away from now.

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

export function verify(secret: string, header: string, rawBody: string, toleranceSecs = 300): boolean {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSecs) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const given = Buffer.from(parts.v1 ?? "", "utf8");
  return given.length === expected.length && timingSafeEqual(given, Buffer.from(expected, "utf8"));
}

import hashlib, hmac, time

def verify(secret: str, header: str, raw_body: bytes, tolerance_secs: int = 300) -> bool:
    parts = dict(part.split("=", 1) for part in header.split(","))
    try:
        t = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > tolerance_secs:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

​

Delivery and retries

• You may get the same update twice. Tern keeps retrying until you respond with 2xx. Ignore repeats by checking the body’s id and status.
• Updates arrive in order for each swap. A later update waits while an earlier one is being retried. Different swaps don’t wait for each other.
• What counts as a failure: any status other than 2xx, no response within 10 seconds, or a redirect.
• When Tern retries: 10 seconds after a failure, then doubling each time, up to an hour apart. After 15 attempts, about 6.5 hours, the delivery is marked as failed. Once your endpoint is back up, email [email protected] and we’ll resend failed deliveries.
• Changing your URL or secret takes effect from the next attempt. A new secret replaces the old one immediately, so update your endpoint right away.