Webhooks

POST /hooks/tahoe HTTP/1.1
Content-Type: application/json
Tahoe-Signature: t=1789245645,v1=6d8b2f...c41a
Tahoe-Partner-Api-Version: 2026-09-09

import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300


def verify(raw_body: bytes, header: str, secret: str) -> bool:
    """True if this delivery really came from Tahoe and is recent.

    `raw_body` MUST be the bytes as received. Re-serialising the parsed JSON
    changes key order and whitespace, and the digest with it.
    """
    # Parsed manually rather than into a dict: there can be MORE THAN ONE v1
    # during a secret rotation, and a dict would keep only the last of them.
    timestamp = None
    signatures = []
    for piece in header.split(","):
        key, _, value = piece.strip().partition("=")
        if key == "t":
            timestamp = value
        elif key == "v1":
            signatures.append(value)

    if not timestamp or not signatures:
        return False

    try:
        stamp = int(timestamp)
    except ValueError:
        return False

    # Reject a replay of an old, validly signed body.
    if abs(int(time.time()) - stamp) > TOLERANCE_SECONDS:
        return False

    expected = hmac.new(
        secret.encode("utf-8"),
        f"{stamp}.".encode("utf-8") + raw_body,
        hashlib.sha256,
    ).hexdigest()

    # compare_digest, never ==: a byte-by-byte comparison leaks the digest.
    return any(hmac.compare_digest(expected, candidate) for candidate in signatures)

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

const TOLERANCE_SECONDS = 300;

export function verify(rawBody: Buffer, header: string, secret: string): boolean {
    let timestamp: string | null = null;
    // More than one v1 arrives during a secret rotation; keep them all.
    const signatures: string[] = [];

    for (const piece of header.split(',')) {
        const [key, value] = piece.trim().split('=', 2);
        if (key === 't') timestamp = value;
        else if (key === 'v1') signatures.push(value);
    }
    if (!timestamp || signatures.length === 0) return false;

    const stamp = Number(timestamp);
    if (!Number.isFinite(stamp)) return false;
    if (Math.abs(Math.floor(Date.now() / 1000) - stamp) > TOLERANCE_SECONDS) return false;

    const expected = createHmac('sha256', secret)
        .update(`${stamp}.`)
        .update(rawBody)
        .digest('hex');

    return signatures.some((candidate) => {
        // timingSafeEqual throws on a length mismatch, so guard first.
        if (candidate.length !== expected.length) return false;
        return timingSafeEqual(Buffer.from(candidate), Buffer.from(expected));
    });
}

{
  "object": "event",
  "id": "evt_7Kd2mXq4Rp8v",
  "type": "application.stage_changed",
  "api_version": "2026-09-09",
  "created_at": "2026-09-08T11:20:45.331Z",
  "sequence": 48214,
  "workspace_id": "wsp_4Kd8sPm2Qx7L",
  "data": {
    "object": {
      "object": "application",
      "id": "app_6Qm2xKd4Rp8v",
      "workspace_id": "wsp_4Kd8sPm2Qx7L",
      "stage_id": "stg_3Rp8vKd2mXq4",
      "updated_at": "2026-09-08T11:20:45.331Z"
    },
    "previous_attributes": { "stage_id": "stg_9Kd2mXq4Rp8v" }
  },
  "links": { "self": "/api/partner/v1/events/evt_7Kd2mXq4Rp8v" }
}

10s → 30s → 2m → 10m → 1h → 6h → 12h → 24h → 24h

{
  "object": "list",
  "data": [
    {
      "object": "webhook_endpoint",
      "id": "8f2c1a94-...",
      "url": "https://hooks.workonward.com/tahoe",
      "description": "HRIS sync",
      "event_types": [],
      "enabled": true,
      "disabled_at": null,
      "disabled_reason": null,
      "signing_secret_version": 2,
      "signing_secret_rotated_at": "2026-08-30T09:00:00.000Z",
      "consecutive_failures": 0,
      "last_success_at": "2026-09-09T09:58:12.004Z",
      "last_failure_at": "2026-08-14T02:11:40.882Z",
      "created_at": "2026-07-01T09:00:00.000Z",
      "signature_scheme": {
        "header": "Tahoe-Signature",
        "format": "t=<unix seconds>,v1=<hex>[,v1=<hex>]",
        "algorithm": "HMAC-SHA256 over \"{t}.{raw_body}\"",
        "tolerance_seconds": 300,
        "note": "Two v1 values appear during a secret rotation. Accept the delivery if EITHER verifies."
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

{
  "object": "list",
  "data": [
    {
      "object": "webhook_delivery",
      "id": "c4e7...",
      "endpoint_id": "8f2c1a94-...",
      "event_id": "evt_7Kd2mXq4Rp8v",
      "event_type": "application.stage_changed",
      "status": "failed",
      "attempt": 3,
      "response_status": 502,
      "error": "upstream returned 502",
      "next_attempt_at": "2026-09-09T10:24:00.000Z",
      "delivered_at": null,
      "created_at": "2026-09-08T11:20:46.112Z"
    }
  ],
  "has_more": true,
  "next_cursor": "cur_eyJrIjoiMjAyNi0wOS0wOFQxMToyMDo0Nloi..."
}