Webhooks

​

Creating a Webhook Endpoint

• URL — your HTTPS endpoint (HTTPS required in production)
• Event types — which events to subscribe to, from the event catalog. Prefix matching is supported: subscribing to "recall" receives every recall.* event, including ones added later — the recommended form for safety-critical domains. Values outside the catalog are rejected with a 422, so a typo can never leave you silently subscribed to nothing.
• API version — the envelope version this endpoint receives. Pinned at creation; we never move it.
• Filters — optional per-event-type filtering rules (AND logic between filter keys, OR within a key)
• Signing secret — auto-generated 64-byte hex secret for payload verification

​

Event Catalog

GET /integrations/api/v1/webhooks/event-types/

​

Recalls & safety

​

Consumer signals

​

Serial verification

​

System

​

Deprecated

​

Envelope Versioning

​

2026-07-01

{
  "specversion": "2026-07-01",
  "type": "recall.opened",
  "id": "evt_a1b2c3d4e5f6",
  "time": "2026-07-29T12:00:00+00:00",
  "source": "closient",
  "cursor": "2026-07-29T12:00:00+00:00~4t3rmMvzGQrqAqZ3vPPGmM",
  "data": {
    "recall_id": "4t3rmMvzGQrqAqZ3vPPGmM",
    "gtins": ["00012345678905"],
    "severity": "CLASS_I",
    "status": "ONGOING"
  }
}

​

v1

{
  "event_type": "recall.opened",
  "version": "v1",
  "event_id": "evt_a1b2c3d4e5f6",
  "timestamp": "2026-07-29T12:00:00+00:00",
  "data": { "recall_id": "4t3rmMvzGQrqAqZ3vPPGmM" }
}

​

Replay on Reconnect

GET /integrations/api/v1/webhooks/events/?after=<cursor>&recalls_only=true

1. Persist the cursor of the last event you durably processed — not the last one you received.
2. On reconnect, call the endpoint with ?after=<that cursor>.
3. Process the page, then repeat using the last cursor on the page, until a page comes back short.

​

Request Headers

​

Verifying Signatures

t=1711972800,v1=5a3c9f...

1. Extract the timestamp (t) and signature (v1) from the header.
2. Construct the signed payload: {timestamp}.{raw_json_body}.
3. Compute HMAC-SHA256 using your signing secret.
4. Compare your computed signature with v1 using a constant-time comparison.
5. Check the timestamp is within your tolerance window (recommended: 5 minutes).

import hashlib
import hmac
import time


def verify_closient_webhook(
    payload: bytes,
    signature_header: str,
    secret: str,
    tolerance_seconds: int = 300,
) -> bool:
    """Verify a Closient webhook signature.

    Args:
        payload: Raw request body bytes.
        signature_header: Value of X-Closient-Signature header.
        secret: Your endpoint's signing secret.
        tolerance_seconds: Max age in seconds (default 5 min).
    """
    # Parse header: t=123,v1=abc...
    parts = {}
    for element in signature_header.split(","):
        key, _, value = element.partition("=")
        parts[key.strip()] = value.strip()

    timestamp = parts.get("t", "")
    if not timestamp:
        return False

    # Replay protection
    age = abs(int(time.time()) - int(timestamp))
    if age > tolerance_seconds:
        return False

    # Compute expected signature
    signed_payload = f"{timestamp}.{payload.decode('utf-8')}"
    expected = hmac.new(
        secret.encode("utf-8"),
        signed_payload.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    # Check current signature (v1), then rotated signature (v1old)
    return (
        hmac.compare_digest(expected, parts.get("v1", ""))
        or hmac.compare_digest(expected, parts.get("v1old", ""))
    )

const crypto = require("crypto");

function verifyClosientWebhook(payload, signatureHeader, secret, toleranceSeconds = 300) {
  // Parse header: t=123,v1=abc...
  const parts = {};
  for (const element of signatureHeader.split(",")) {
    const [key, ...rest] = element.split("=");
    parts[key.trim()] = rest.join("=").trim();
  }

  const timestamp = parts.t;
  if (!timestamp) return false;

  // Replay protection
  const age = Math.abs(Math.floor(Date.now() / 1000) - parseInt(timestamp, 10));
  if (age > toleranceSeconds) return false;

  // Compute expected signature
  const signedPayload = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signedPayload, "utf-8")
    .digest("hex");

  // Check current signature (v1), then rotated signature (v1old)
  const v1Match = crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(parts.v1 || "", "hex").subarray(0, 32)
  );
  if (v1Match) return true;

  if (parts.v1old) {
    return crypto.timingSafeEqual(
      Buffer.from(expected, "hex"),
      Buffer.from(parts.v1old, "hex").subarray(0, 32)
    );
  }

  return false;
}

​

Secret Rotation

t=1711972800,v1=<current_secret_sig>,v1old=<previous_secret_sig>

​

Delivery Lifecycle

​

Retry Policy

POST /integrations/api/v1/webhooks/deliveries/{delivery_id}/replay/

​

Auto-Disable

​

Testing

POST /integrations/api/v1/webhooks/endpoints/{endpoint_id}/test/

​

Best Practices

• Return 2xx quickly — acknowledge receipt, then process asynchronously. Closient times out after 30 seconds.
• Handle duplicates — use the id field (event_id on v1) for idempotency. The same event may arrive more than once via retries or a replay.
• Checkpoint your cursor — persist the cursor of the last event you durably processed, so an outage becomes a replay rather than a silent gap. For recall events this is the difference between a feed you can rely on and one that manufactures false confidence.
• Verify signatures — always validate X-Closient-Signature before processing. Reject unsigned or expired requests.
• Use HTTPS — required in production. HTTP is only allowed in development.
• Monitor health — check delivery status in the Dashboard or via the Integrations API. Address failures before they accumulate into auto-disable.