Normal generation-event delivery
For subscribed generation events, BabySea attempts delivery and records the outcome in the delivery log shown on Webhook details.
Each delivery attempt includes:
X-BabySea-SignatureX-BabySea-EventX-BabySea-TimestampX-BabySea-Delivery-Id- A JSON body with the same event data
What causes another attempt
BabySea retries a delivery when your endpoint:
| Condition | Description |
|---|
| Non-2xx response | Any HTTP status outside the 200-299 range, including 3xx redirects |
| Timeout | Your endpoint does not respond promptly |
| Connection error | TCP connection refused, DNS failure, TLS handshake error |
2xx responses count as successful delivery.
Retry behavior
For generation events, BabySea retries failed deliveries for a limited period before marking the delivery as failed in the log.
Auto-disable
If a webhook endpoint continues to fail repeatedly, BabySea can disable it automatically to avoid repeated failed delivery attempts.
When auto-disable happens:
| What happens | Details |
|---|
| Webhook status changes to Disabled | Visible as a red badge in your dashboard |
| Matching events can remain available for later redelivery | Use the dashboard to resume delivery when ready |
| No deliveries are attempted | Until you re-enable the webhook |
Queued redelivery
When a webhook is unavailable, BabySea can keep eligible generation events available for later redelivery from the dashboard.
Queued events are not retained forever. Re-enable a disabled webhook and redeliver queued events promptly if they appear on the page.
Deliver queued events
After re-enabling a webhook, you can deliver all queued events from the webhook details page:
Re-enable the webhook
Toggle the status switch to Enabled on the Webhook details page.
Click Deliver queued events
A banner appears when there are pending queued items. Click Deliver queued events to start redelivery.
BabySea re-delivers queued items
Each queued event is sent with a fresh delivery ID, fresh timestamp, and a fresh HMAC signature. The original event payload is preserved.
| Behavior | Details |
|---|
| Retries | A fresh delivery attempt is created for each queued event |
| Signatures | Fresh HMAC signature computed for each delivery |
| Delivery IDs | New UUID for each delivery (not the original) |
| Active webhook required | Yes. The endpoint must be enabled before drain can run |
webhook.test is for manual verification only. Use Send test event when you want a fresh test delivery.
Replaying deliveries
You can manually replay a previous delivery from the Webhook events table on Webhook details.
| Property | Value |
|---|
| Delivery ID | Fresh UUID (not the original) |
| Timestamp | Fresh ISO 8601 timestamp |
| Signature | Fresh HMAC computed with current secret |
| Payload | Original webhook_data preserved exactly |
| Retries | Creates a new manual delivery attempt |
| Active webhook required | Yes |
- Recovering from transient processing failures in your handler.
- Testing changes to your webhook processing logic against real payloads.
- Re-delivering events after fixing a bug in your endpoint.
Events table
The webhook details page includes the Webhook events table with these columns:
| Column | Description |
|---|
| Event | The webhook_event value (e.g., generation.completed) |
| Generation ID | The generation_id from the payload |
| Status | HTTP response code from your endpoint, color-coded by outcome |
| Error | Error message if the delivery failed |
| Attempts | Number of delivery attempts made |
| Delivered at | The recorded delivery timestamp |
| Actions | Resend button for manual replay |
| Color | Meaning |
|---|
| Green | 2xx success |
| Blue | 3xx redirect |
| Amber | 4xx client error |
| Red | 5xx server error |
Webhook statuses
A webhook can be in one of two statuses:
| Status | Badge | Deliveries | Queued redelivery behavior |
|---|
| Enabled | Green | Active | Not used |
| Disabled | Red | Paused | Eligible generation events can be redelivered later |
| Cause | How it happens |
|---|
| Manual | You toggle the status switch on the webhook details page |
| Auto-disable | BabySea disables it after repeated delivery failures |
Enable and disable
Toggle the status switch on the Webhook details page to enable or disable a webhook. Only Owner and Primary Owner roles can toggle status.
When you disable a webhook:
- BabySea stops delivering events to the endpoint immediately.
- If no other active webhook can receive the event, eligible generation events can remain available for later redelivery.
- The delivery log is preserved.
When you re-enable a webhook:
- BabySea resumes delivering new events immediately.
- A banner appears if there are pending queued items. Click Deliver queued events to send them.
Rotate secret
If your webhook secret is compromised or you want to refresh it on a regular schedule, generate a new secret from the webhook details page.
Open Webhook details
Navigate to the Webhook details page for the endpoint you want to update.
Click Rotate secret
Click Rotate secret. The dialog says the old secret will stop working immediately.
Copy the new secret
The new secret is displayed in a dialog:whsec_x9Y8z7W6v5U4t3S2r1Q0p9O8n7M6l5K4
Copy this secret immediately. It is shown only once and cannot be retrieved later.
Update your environment
Replace the old secret in your environment variables and redeploy before any new events arrive:BABYSEA_WEBHOOK_SECRET=whsec_x9Y8z7W6v5U4t3S2r1Q0p9O8n7M6l5K4
| What happens | Details |
|---|
| Old secret is invalidated immediately | All new deliveries use the new secret |
There is no grace period where both old and new secrets are accepted simultaneously. Update your endpoint to use the new secret before BabySea sends the next event.
Send test event
Click Send test event on the Webhook details page to verify your endpoint is reachable and correctly verifying signatures.
| Property | Value |
|---|
| Event type | webhook.test |
| Purpose | Confirm that your endpoint receives and verifies a signed delivery |
| Delivery result | Logged in the Webhook events table |
webhook.test deliveries are logged in the Webhook events table, but they cannot be replayed from the row action. Use Send test event again instead.
Delete endpoint
Click Delete on the Webhook details page to permanently remove a webhook endpoint.
| What is removed | Details |
|---|
| Webhook configuration | URL, events, secret, status |
| All delivery logs | Full event history for this endpoint |
| Queued delivery state | Any queued items associated with this endpoint |
Deletion is permanent and cannot be undone. All delivery history and queued events are lost. If you only need to temporarily stop deliveries, use the disable toggle instead.
