Signature verification

When your organization has a webhook secret configured, every webhook delivery includes four signed headers so your receiver can verify the payload came from Tumban, hasn’t been tampered with, and is meant for your organization.

Headers

Header	Meaning
`X-Tumban-Signature`	`sha256=<hex>` — HMAC-SHA256 over the raw request body. Simplest receiver implementation.
`X-Tumban-Signature-V2`	`sha256=<hex>` — HMAC-SHA256 over `"{timestamp}.{org_id}.{body}"`. Recommended — adds replay resistance and tenant binding.
`X-Tumban-Timestamp`	Unix seconds when the payload was signed.
`X-Tumban-Org-Id`	The `org_id` this webhook is for.

Both signatures use the same secret. The signed payload is built from raw bytes, not a decoded string — the V2 string-to-sign is the UTF-8 encoding of "{timestamp}.{org_id}." concatenated with the request body bytes. Verify before parsing JSON, since any whitespace or key reordering you apply will change the bytes.

Under rare error paths Tumban sends X-Tumban-Org-Id: "" (empty string) — this happens when the worker that fired the webhook lost its organization context. The V2 verifier above already rejects these payloads because the empty header value will not match EXPECTED_ORG_ID. Treat any webhook with an empty X-Tumban-Org-Id as suspicious.

Setting up

Generate a webhook secret

Call Rotate webhook secret (or use the dashboard — see that page). The value is shown exactly once.

Store the secret

Put it in your secret manager. Capture the org_id your receiver expects to receive webhooks for at the same time — you’ll bind the receiver to it.

Verify every incoming webhook

Use the V2 verifier below. It performs all three required checks: constant-time signature compare, replay window, and tenant binding.

What your verifier must do

A correct verifier performs three checks in addition to recomputing the signature:

Constant-time signature compare. Do not use == on the hex digest. Use hmac.compare_digest (Python), crypto.timingSafeEqual (Node), or your language’s equivalent. A naive == leaks timing information that lets an attacker brute-force a valid signature byte by byte.
Replay protection. Reject anything whose X-Tumban-Timestamp is more than ~5 minutes from now. Captured signed payloads should not be replayable indefinitely.
Tenant binding. Verify X-Tumban-Org-Id matches the org_id your receiver expects. Without this, a webhook signed with org A’s secret can be delivered to a receiver that hardcodes one secret and accepts any “from us” payload — a cross-tenant abuse vector.

Reference verifier (V2 — recommended)

import hashlib
import hmac
import time

WEBHOOK_SECRET   = "..."          # the secret from Rotate webhook secret
EXPECTED_ORG_ID  = "org_abc123"   # the org_id this receiver belongs to
TOLERANCE_SECONDS = 300           # 5 minutes


def verify_webhook(headers: dict, body: bytes) -> bool:
    """Return True iff headers + body authenticate as a valid Tumban
    webhook for EXPECTED_ORG_ID, signed within TOLERANCE_SECONDS.
    """
    sig_header = headers.get("X-Tumban-Signature-V2", "")
    timestamp  = headers.get("X-Tumban-Timestamp", "")
    org_id     = headers.get("X-Tumban-Org-Id", "")

    if not sig_header.startswith("sha256="):
        return False
    received_sig = sig_header[len("sha256="):]

    # 1. Tenant binding — reject anything not for our org.
    if org_id != EXPECTED_ORG_ID:
        return False

    # 2. Replay protection — reject stale or future timestamps.
    try:
        sent_at = int(timestamp)
    except ValueError:
        return False
    if abs(int(time.time()) - sent_at) > TOLERANCE_SECONDS:
        return False

    # 3. Constant-time signature check.
    signed_payload = f"{timestamp}.{org_id}.".encode() + body
    expected = hmac.new(WEBHOOK_SECRET.encode(), signed_payload,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(received_sig, expected)

import crypto from "node:crypto";

const WEBHOOK_SECRET    = "...";          // the secret from Rotate webhook secret
const EXPECTED_ORG_ID   = "org_abc123";   // the org_id this receiver belongs to
const TOLERANCE_SECONDS = 300;            // 5 minutes


export function verifyWebhook(headers, body) {
  const sigHeader = headers["x-tumban-signature-v2"] || "";
  const timestamp = headers["x-tumban-timestamp"]    || "";
  const orgId     = headers["x-tumban-org-id"]       || "";

  if (!sigHeader.startsWith("sha256=")) return false;
  const receivedSig = sigHeader.slice("sha256=".length);

  // 1. Tenant binding.
  if (orgId !== EXPECTED_ORG_ID) return false;

  // 2. Replay protection.
  const sentAt = parseInt(timestamp, 10);
  if (Number.isNaN(sentAt)) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - sentAt) > TOLERANCE_SECONDS) {
    return false;
  }

  // 3. Constant-time signature check. `body` must be the raw bytes.
  const signedPayload = Buffer.concat([
    Buffer.from(`${timestamp}.${orgId}.`, "utf8"),
    body,
  ]);
  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(signedPayload)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(receivedSig, "hex"),
  );
}

require "openssl"

WEBHOOK_SECRET    = "..."          # the secret from Rotate webhook secret
EXPECTED_ORG_ID   = "org_abc123"   # the org_id this receiver belongs to
TOLERANCE_SECONDS = 300            # 5 minutes


def verify_webhook(headers, body)
  sig_header = headers["X-Tumban-Signature-V2"].to_s
  timestamp  = headers["X-Tumban-Timestamp"].to_s
  org_id     = headers["X-Tumban-Org-Id"].to_s

  return false unless sig_header.start_with?("sha256=")
  received_sig = sig_header.delete_prefix("sha256=")

  # 1. Tenant binding.
  return false unless org_id == EXPECTED_ORG_ID

  # 2. Replay protection.
  sent_at = Integer(timestamp) rescue nil
  return false if sent_at.nil?
  return false if (Time.now.to_i - sent_at).abs > TOLERANCE_SECONDS

  # 3. Constant-time signature check.
  signed_payload = "#{timestamp}.#{org_id}.".b + body
  expected = OpenSSL::HMAC.hexdigest("sha256", WEBHOOK_SECRET, signed_payload)

  Rack::Utils.secure_compare(expected, received_sig)
end

Choosing between V1 and V2

V2 (X-Tumban-Signature-V2) is recommended for all new receivers. It binds the signature to a specific tenant and timestamp, defending against replay and cross-tenant abuse.
V1 (X-Tumban-Signature) is shipped on every delivery for receivers that need the simplest possible HMAC-over-body implementation. It does not bind tenant or timestamp — if you use it, rotate secrets aggressively and never share a secret across orgs.

# V1-only verifier (for completeness; prefer V2):
def verify_v1(secret: str, body: bytes, header_value: str) -> bool:
    if not header_value.startswith("sha256="):
        return False
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    received = header_value[len("sha256="):]
    return hmac.compare_digest(expected, received)

Rotation

When you rotate the secret, Tumban switches over immediately — incoming webhooks are signed with the new secret only. Update your verification code first, then call Rotate webhook secret.

When the headers are absent

If your organization has no webhook secret configured, Tumban does not send any of the four signature headers. Generate one with Rotate webhook secret before trusting webhook bodies in production.

Get started

Core concepts

API reference

Webhooks

Reference

Signature verification

Headers

Setting up

What your verifier must do

Reference verifier (V2 — recommended)

Choosing between V1 and V2

Rotation

When the headers are absent

​Headers

​Setting up

​What your verifier must do

​Reference verifier (V2 — recommended)

​Choosing between V1 and V2

​Rotation

​When the headers are absent

Headers

Setting up

What your verifier must do

Reference verifier (V2 — recommended)

Choosing between V1 and V2

Rotation

When the headers are absent