Client webhooks

Client Webhooks let you receive real-time notifications when events occur in your Cognis organization. Configure endpoints (URLs) in Org Settings → Webhooks, subscribe to event types, and Cognis sends signed HTTP POST requests to your URLs.

Key properties

• At-least-once delivery: Events may be retried; your endpoint must handle duplicates (use Cognis-Event-Id or Cognis-Delivery-Id for idempotency).
• Non-guaranteed ordering: Events can arrive out of order.
• Immutable payloads: Retries resend the exact same body.

Signature verification

Cognis signs each webhook with HMAC. Always verify the signature before processing. The signed payload is timestamp + "." + raw_body (exact string, no normalization). Algorithm: HMAC-SHA256 with your endpoint secret; output as base64.

Header: Cognis-Signature: t=<timestamp>,v1=<hmac_base64>

Steps: (1) Extract t and v1 from the header. (2) Recompute HMAC over t + "." + raw_body using your secret. (3) Compare with v1 using a timing-safe comparison. (4) Reject if |now - t| > 300 seconds.

Headers

Cognis-Event-Id, Cognis-Event-Type, Cognis-Delivery-Id, User-Agent: Cognis-Webhooks/1.0

Raw body required

Use the raw request body (before JSON parsing) for signature verification. In Express, use express.raw with type: 'application/json' for the webhook route so the body stays as a Buffer.

Retries

Retryable: timeout, DNS/connect errors, 429, 5xx. Non-retryable: 400, 401, 403, 404, 410. Backoff: 1m, 5m, 15m, 1h, 6h, 24h. After 20 consecutive failures, the endpoint is auto-disabled.