What are webhooks?
Image generation is asynchronous. When you callPOST /image-generation/{model_identifier}, BabySea returns a generation_id immediately and begins processing in the background. Webhooks let BabySea notify your server the moment that processing finishes, instead of your code polling GET /image-generation/{generation_id} repeatedly.
When does BabySea send a webhook?
BabySea sends aPOST request to your endpoint for these events:
| Event | When |
|---|---|
generation.started | The generation was submitted to an inference provider |
generation.completed | All output images are ready |
generation.failed | All inference providers were exhausted without success |
generation.canceled | The generation was canceled by the user |
webhook.test | You clicked Send test event in your workspace |
webhook_data object with a snapshot of the generation at the time of the event. See Events for the full payload reference.
Endpoint requirements
Your webhook endpoint must:- Accept
POSTrequests with aContent-Type: application/jsonbody. - Respond with any
2xxstatus code within 10 seconds. - Be publicly reachable over HTTPS.
2xx response or times out, BabySea will retry the delivery up to 5 times with exponential backoff. See Retry and delivery for the full retry schedule and auto-disable behavior.
Request headers
Every delivery includes the following HTTP headers:| Header | Description |
|---|---|
Content-Type | Always application/json |
X-BabySea-Signature | HMAC-SHA256 signature, see Verify signature |
X-BabySea-Event | Event type, e.g. generation.completed |
X-BabySea-Delivery-Id | UUID matching webhook_delivery_id in the payload (use as an idempotency key) |
X-BabySea-Timestamp | ISO 8601 timestamp matching webhook_timestamp in the payload |
Setting up your endpoint
- Navigate to your workspace in the BabySea dashboard.
- Add a webhook URL. BabySea generates a signing secret, copy it immediately, it is shown only once.
- Select which events to subscribe to (all four are enabled by default).
- Click Send test event to verify your endpoint is reachable and correctly verifying signatures.
BABYSEA_WEBHOOK_SECRET). Never commit it to source code. If you suspect your secret has been compromised, rotate it from your workspace, and BabySea signs all new deliveries with the new secret immediately.
Delivery guarantees
Because BabySea guarantees at-least-once delivery, your endpoint may receive the same event more than once (e.g., during infrastructure failover). Use thewebhook_delivery_id as an idempotency key to avoid processing duplicates. See Retry and delivery for details.
| Property | Guarantee |
|---|---|
| Delivery | At least once |
| Ordering | Not guaranteed across events |
| Idempotency | Use webhook_delivery_id |
| Retry | Up to 5 attempts (exponential) |
| Auto-disable | After 15 consecutive failures |
| DLQ retention | 72 hours |