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 structured filters, scoped to the recall payload shape (see Filters below)
• Signing secret — auto-generated whsec_-prefixed secret for payload verification. Shown once; store it somewhere you can read it back. Endpoints created before this format shipped keep their existing secret, which stays valid.

​

Destination requirements

{
  "type": "https://docs.closient.com/errors/validation_error",
  "title": "Validation Error",
  "status": 422,
  "detail": "hooks.example.com resolved to 10.0.0.7, which is in 10.0.0.0/8 — private (RFC 1918).",
  "details": {
    "field_errors": {
      "url": ["hooks.example.com resolved to 10.0.0.7, which is in 10.0.0.0/8 — private (RFC 1918)."]
    }
  }
}

​

Per-organization limits

​

Endpoint verification

OPTIONS /webhooks/closient HTTP/1.1
Host: hooks.example.com
WebHook-Request-Origin: www.closient.com
WebHook-Request-Rate: 120
User-Agent: Closient-Webhooks/1.0

HTTP/1.1 200 OK
WebHook-Allowed-Origin: www.closient.com
WebHook-Allowed-Rate: 120

• WebHook-Allowed-Origin — required. Either the exact value of WebHook-Request-Origin, or *. A comma-separated list is accepted.
• WebHook-Allowed-Rate — optional, requests per minute you are willing to accept, or *. We record it; we do not yet pace deliveries against it.

def closient_webhook(request):
    if request.method == "OPTIONS":
        response = HttpResponse(status=200)
        response["WebHook-Allowed-Origin"] = request.headers.get("WebHook-Request-Origin", "*")
        response["WebHook-Allowed-Rate"] = "120"
        return response
    ...  # verify the signature, then handle the event

app.options("/webhooks/closient", (req, res) => {
  res.set("WebHook-Allowed-Origin", req.get("WebHook-Request-Origin") || "*");
  res.set("WebHook-Allowed-Rate", "120");
  res.sendStatus(200);
});

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

​

Filters

​

Event Catalog

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

​

Recalls & safety

​

Consumer signals

​

Serial verification

​

Scans & resolves

​

Traceability

​

Catalog

​

System

​

Deprecated

​

Envelope Versioning

​

cloudevents-1.0

{
  "specversion": "1.0",
  "type": "recall.opened",
  "source": "https://www.closient.com/recalls",
  "id": "evt_a1b2c3d4e5f6",
  "time": "2026-09-17T12:00:00+00:00",
  "datacontenttype": "application/json",
  "recallgdti": "0123456789012",
  "recordversion": 3,
  "jurisdiction": "US,CA",
  "cursor": "2026-09-17T12:00:00+00:00~4t3rmMvzGQrqAqZ3vPPGmM",
  "data": {
    "recall_id": "4t3rmMvzGQrqAqZ3vPPGmM",
    "gdti": "0123456789012",
    "record_version": 3,
    "canonical_url": "https://www.closient.com/pip/00012345678905/recall/4t3rmMvzGQrqAqZ3vPPGmM",
    "gtins": ["00012345678905"],
    "severity": "CLASS_I",
    "status": "ONGOING"
  }
}

​

Routing extension attributes

​

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

​

Identifying our requests

User-Agent: Closient-Webhooks/1.0

​

Verifying Signatures (cloudevents-1.0)

# pip install standardwebhooks
from standardwebhooks import Webhook

wh = Webhook(endpoint_signing_secret)      # the whsec_... secret from your endpoint
event = wh.verify(raw_request_body, dict(request.headers))

// npm install standardwebhooks
import { Webhook } from "standardwebhooks";

const wh = new Webhook(endpointSigningSecret);
const event = wh.verify(rawRequestBody, headers);

​

The scheme, if you’d rather implement it

1. Read webhook-id, webhook-timestamp and webhook-signature.
2. Reject if webhook-timestamp is more than 300 seconds away from now, in either direction. A timestamp far in the future is as suspicious as a stale one, and a one-sided check rejects honest clock skew. This is your replay protection — nothing else bounds how long a captured delivery stays valid.
3. Derive the key: strip the whsec_ prefix and base64-decode the rest. The key is those bytes, not the string.
4. Compute base64(HMAC-SHA256(key, "{webhook-id}.{webhook-timestamp}.{raw_body}")). Sign the raw bytes you received — re-serialising the parsed JSON changes key order and separators, and therefore the signature.
5. webhook-signature holds one or more space-delimited v1,<base64> tokens. Accept if any v1 token matches, using a constant-time comparison. Skip tokens with an unrecognised version prefix rather than rejecting the whole header.

import base64, hashlib, hmac, time

def verify_closient_webhook(body: str, headers, secret: str, tolerance: int = 300) -> bool:
    """Verify a Closient `cloudevents-1.0` delivery. `body` is the raw request body."""
    h = {k.lower(): v for k, v in headers.items()}
    msg_id, timestamp, signature = h.get("webhook-id"), h.get("webhook-timestamp"), h.get("webhook-signature")
    if not (msg_id and timestamp and signature):
        return False

    if abs(int(time.time()) - int(timestamp)) > tolerance:
        return False  # stale or implausibly future — replay protection

    key = base64.b64decode(secret.removeprefix("whsec_") + "==")
    expected = base64.b64encode(
        hmac.new(key, f"{msg_id}.{timestamp}.{body}".encode(), hashlib.sha256).digest()
    ).decode()

    return any(
        hmac.compare_digest(expected, token.split(",", 1)[1])
        for token in signature.split(" ")
        if token.startswith("v1,")
    )

​

Rotating a signing secret with no gap

webhook-signature: v1,<signed with the new secret> v1,<signed with the previous secret>

​

Verifying Signatures (2026-07-01 and v1)

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 (legacy envelopes)

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

​

Delivery Guarantees

• At-least-once. Every event is delivered at least once to an active endpoint, or recoverable from the feed if it is not. The same event can arrive more than once: a retry after a response we never saw, a worker restart mid-send, a manual replay, and catch-up from a cursor all resend. Deduplicate on the CloudEvents id (event_id on v1), which is stable across every retry, replay and feed read of the same event.
• No ordering guarantee. Events are sent independently, so a retry of an older event can land after a newer one, and one slow event never holds up the ones behind it. Do not infer order from arrival.
• Recall amendments: newest record_version wins. A recall is identified by its GDTI (recallgdti, and gdti inside data), and record_version increases every time the recall changes meaningfully. Keep the highest record_version you have applied per GDTI and discard any event carrying a lower one — that is how an out-of-order arrival stops overwriting a newer amendment.

​

Delivery Lifecycle

​

Retry Policy

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

​

Timeouts

​

Auto-Disable

• 20 consecutive delivery attempts fail with no success in between (any 2xx resets the count), or
• every delivery in the last 24 hours failed, across at least three deliveries. The window never reaches back past the endpoint’s last state change, so a re-enabled endpoint is judged only on what happened since.

GET /integrations/api/v1/webhooks/events/?after=<catch_up_cursor>

​

Testing

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

​

Best Practices

• Return 2xx quickly — acknowledge receipt, then process asynchronously. Closient gives each attempt 5 seconds to connect and 15 to respond; see Timeouts.
• Handle duplicates and reordering — use the id field (event_id on v1) for idempotency, and keep the highest record_version per recall GDTI. See Delivery Guarantees.
• 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 the signature before processing, and reject unsigned or expired requests. On cloudevents-1.0 that means webhook-signature plus the 300-second webhook-timestamp window; on a legacy pin, X-Closient-Signature.
• Use HTTPS, on a publicly reachable host — enforced everywhere, with no development exemption, and re-checked before every delivery. See Destination requirements.
• Monitor health — check delivery status in the Dashboard or via the Integrations API. Address failures before they accumulate into auto-disable.