Skip to main content

Overview

Webhooks let your server receive notifications when asynchronous events complete - for example, when a generation job finishes. Every delivery is signed so you can verify it originated from the platform. Webhooks are project-scoped: a subscription belongs to one project, and every endpoint URL is re-validated against an SSRF blocklist on each delivery attempt.

Registering an endpoint

Store the secret value - it is shown only once and is used to verify signatures. Lost it? Use the rotate-secret endpoint to get a new one.

Verifying signatures

Each delivery includes three headers: The signed payload is {timestamp}.{raw_request_body}. Reject events older than 5 minutes to defend against replay.

Event catalog

Delivery and retries

  • Deliveries time out after 10 seconds.
  • Failed deliveries (non-2xx, timeout, or connection error) are retried with exponential backoff: 5s, 30s, 2m, 15m, 1h, 4h (7 attempts including the initial one; ~5h 18m total window).
  • After 3 consecutive failed events on the same endpoint, the endpoint is auto-disabled and a notification is sent to the project owner. Re-enable it by PATCHing { "active": true }.

Managing endpoints