Skip to main content

Prerequisites

Before creating a webhook, make sure you:
  • Have a BabySea account (personal or team).
  • Are signed in to the dashboard.
  • Have an owner-level role on the account. Members can view the page, but cannot create or manage endpoints.
  • Have a public endpoint ready to receive POST requests.

Step by step

1

Open Webhook

Navigate to Webhook in the sidebar. You will see a list of all registered endpoints for your account.
2

Click Add endpoint

Click Add endpoint in the top right corner. The dialog title is Add webhook endpoint.
3

Enter your URL

Enter the Endpoint URL value for your handler:
https://api.example.com/webhooks/babysea
The current dashboard validates this field as a URL.
4

Select events

In the Event types section, choose which generation events this endpoint should receive. All four are selected by default:
Checkbox labelEvent value
Generation Startedgeneration.started
Generation Completedgeneration.completed
Generation Failedgeneration.failed
Generation Canceledgeneration.canceled
The manual event webhook.test is not part of this checkbox list. It is sent from Send test event on the details page.
5

Click Add

Click Add to create the endpoint.
6

Store the webhook secret

After creation, BabySea opens the Webhook secret dialog and shows the secret once:
whsec_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6
Copy this secret immediately. It is shown only once and cannot be retrieved later. If you lose it, you will need to rotate it from the Webhook details page.
The dialog includes Show value, Hide value, a copy button, and Done.Store the secret as an environment variable. Never commit it to source code:
.env
BABYSEA_WEBHOOK_SECRET=whsec_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6
7

Send a test event

Open the new row to reach Webhook details, then click Send test event. BabySea sends a webhook.test request with the fixed generation ID 00000000-0000-0000-0000-000000000000.Use this to verify:
  • Your endpoint is reachable over HTTPS.
  • Your signature verification logic is working correctly.
  • Your handler returns a 2xx response within 10 seconds.
Test events are limited to one send per webhook every 30 seconds and use a single delivery attempt.

What you see after creation

The webhook list page shows your new endpoint with:
ColumnDescription
EndpointYour endpoint URL. Click to open the details page
StatusGreen Enabled badge or red Disabled badge
CreatedDate the webhook was created
ActionsMenu with Delete

Webhook details page

Click a webhook URL to open its details page. This page shows:
SectionWhat it contains
Endpoint URLYour URL with a copy button
Status toggleSwitch to enable or disable the webhook
EventsBadges showing which events the endpoint receives
Webhook secretThe stored secret prefix followed by masked characters
CreatedWhen the webhook was registered
Action buttonsSend test event, Rotate secret, Delete
Below the webhook info, the Webhook events table shows a full delivery log. See Retry and delivery for details on managing your webhook from this page.

Implement your endpoint

Set up a handler that verifies the signature and acknowledges the delivery immediately. Process the payload asynchronously to stay within the 10-second response window.
TypeScript
// app/api/webhooks/babysea/route.ts
import { verifyWebhook } from 'babysea/webhooks';

export async function POST(req: Request) {
  const rawBody = await req.text();
  const signature = req.headers.get('x-babysea-signature') ?? '';

  try {
    const payload = await verifyWebhook(
      rawBody,
      signature,
      process.env.BABYSEA_WEBHOOK_SECRET!,
    );

    // Acknowledge first, then process async
    await queue.push(payload);

    return new Response('OK', { status: 200 });
  } catch {
    return new Response('Invalid signature', { status: 400 });
  }
}
See Verify signature for the full manual verification walkthrough and troubleshooting guide.