Webhooks

Closku webhooks deliver real-time notifications when events occur in the platform. Each event has a type, a unique ID, and a payload with the relevant data:

Note: catalog.updated, subscription.changed, and usage.limit_reached events are planned for a future release and not yet available.

Assume events can arrive more than once and may not arrive in the sequence your application prefers. Your consumers should be correct under replay and partial delay. Use the event ID to de-duplicate: store processed event IDs and skip replays. Closku retries failed deliveries with exponential backoff for up to 24 hours. Events are delivered at-least-once, so use event timestamps for ordering rather than delivery order. Respond with 200 within 5 seconds, as slow handlers risk retries and duplicate processing.

Your webhook endpoint must respond with HTTP 200 to acknowledge receipt (the response body is not inspected). It needs to be publicly accessible via HTTPS, validate the webhook signature using the shared secret to verify the payload is from Closku, and handle payloads up to 1MB. If a consumer cannot process an event safely, return a non-2xx status and Closku will retry. Do not silently drop events that fail processing.