Webhooks

Documentation Index

Fetch the complete documentation index at: https://docs.closient.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Creating a Webhook Endpoint

• URL — your HTTPS endpoint (HTTPS required in production)
• Event types — which events to subscribe to (e.g., ["offer.updated", "product.recalled"]). Prefix matching is supported: subscribing to "offer" receives all offer.* events.
• 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

​

Payload Format

{
  "id": "evt_a1b2c3d4e5f6",
  "type": "offer.updated",
  "created_at": "2026-04-01T12:00:00+00:00",
  "data": {
    "gtin": "00012345678905",
    "offer_id": "ack3p9tw6x7r"
  }
}

​

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 for idempotency. The same event may be delivered more than once during retries.
• 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.