Skip to main content
Webhooks let BabySea send subscribed events to your server with an HTTP POST request. They are useful when you do not want to poll GET /v1/content/{generation_id} after each generation request, and they can also notify you about credit alerts.

​
What you see in the dashboard

The Webhook workspace has two levels:
  • Webhook - the list page with Add endpoint, search, and the endpoint table.
  • Webhook details - the detail page for one endpoint, including status, events, secret tools, queued events, and the Webhook events table.

​
Event types

The create dialog lets you subscribe an endpoint to these delivery events:
EventWhen BabySea sends it
generation.startedThe generation has been submitted and is processing.
generation.completedThe generation finished successfully.
generation.failedThe generation finished with a failure state.
generation.canceledThe generation was canceled.
credits.low_balanceThe account balance crosses one or more configured alert thresholds.
The dashboard also supports the manual event webhook.test when you click Send test event on Webhook details.

​
How delivery works

When a subscribed generation event occurs, BabySea uses this delivery flow:
1

Load active endpoints

BabySea looks up the active webhook endpoints for the account.
2

Filter by event subscription

Only endpoints subscribed to the current event are selected.
3

Build the payload

BabySea creates a JSON payload with webhook_event, webhook_timestamp, webhook_delivery_id, and webhook_data.
4

Sign the payload

BabySea signs the raw JSON with HMAC-SHA256 and sends the signature in X-BabySea-Signature.
5

Send the request

BabySea sends an HTTP POST request to your subscribed endpoint.
6

Retry failed delivery attempts

For generation events, BabySea may retry failed deliveries for a limited period before marking the attempt as failed.
If multiple webhooks subscribe to the same event, BabySea delivers that event to each subscribed endpoint. Delivery behavior can vary by event type. For integration purposes, rely on the documented payload shape and your endpoint’s ability to verify and acknowledge deliveries.

​
Request headers

Every delivery includes these HTTP headers:
HeaderDescription
Content-TypeAlways application/json
X-BabySea-SignatureHMAC-SHA256 signature for verification. See Verify signature
X-BabySea-EventEvent type, for example generation.completed
X-BabySea-Delivery-IdDelivery ID that also appears in the payload
X-BabySea-TimestampTimestamp value that also appears in the payload
The body still contains the canonical event payload. The extra headers are convenient for logging, filtering, or request tracing.

​
Reliability behavior

BabySea records delivery results in the dashboard and can temporarily pause or delay delivery to endpoints that are repeatedly failing. If a webhook becomes unavailable, re-enable it promptly and review the delivery log before resuming production traffic.

​
Disabled endpoints and queued events

If a webhook is unavailable, BabySea may keep eligible generation events available for later delivery from the dashboard. On Webhook details, queued items appear in a banner above the events table with the action Deliver queued events. Queued delivery availability is limited. Re-enable and drain queued events promptly when they appear.

​
Secret handling

Each endpoint has a webhook secret used for signature verification.
  • The secret is shown once when you create the endpoint.
  • The detail page shows only the secret prefix.
  • Rotate secret creates a new secret and invalidates the old one immediately.

​
Access and management

Members can view webhook pages, but create, toggle, rotate, replay, drain, and delete actions are restricted to owner-level users.

​
Next steps

  • Setup - Step by step guide to creating a webhook endpoint
  • Events - All event types and their payload structures
  • Verify signature - How to verify that a delivery came from BabySea
  • Retry & delivery - Automatic retries, test events, replay, and queued delivery behavior