Skip to main content
Webhooks let BabySea send generation 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.

​
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.
The dashboard also supports the manual event webhook.test when you click Send test event on Webhook details.

​
How delivery works

When a 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 whose stored event list includes 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 with a 10 second timeout.
6

Retry failed delivery attempts

For normal generation events, BabySea retries failed deliveries up to 5 attempts using delays of 0s, 1s, 4s, 16s, and 60s.
If multiple webhooks subscribe to the same event, BabySea delivers to all of them in parallel.

​
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

The current webhook implementation includes these delivery controls:
BehaviorCurrent implementation
Normal delivery attemptsUp to 5 attempts per delivery
Delivery timeout10 seconds
Auto-disable threshold15 consecutive failures
Disabled-endpoint queue retention72 hours
If a webhook accumulates 15 consecutive failed deliveries, BabySea disables it automatically.

​
Disabled endpoints and queued events

When BabySea has no active webhook to deliver for the account, it checks disabled webhooks and can queue matching events in the dead letter queue for later delivery. On Webhook details, queued items appear in a banner above the events table with the action Deliver queued events. Queued items expire after 72 hours if you do not re-enable and drain them in time.

​
Secret handling

Each endpoint has a webhook secret used for HMAC 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 and delivery - Automatic retries, test events, replay, and queued delivery behavior