Webhooks

• Verify signatures. Always verify webhook signatures before processing events to ensure authenticity
• Respond quickly. Return a 2xx status code within 10 seconds to acknowledge receipt
• Use HTTPS. Always use HTTPS endpoints in production for secure communication
• Secure secrets. Store webhook secrets in environment variables, never in code
• Implement idempotency. Use the webhook id field to prevent duplicate processing of the same event
• Handle retries. Failed webhooks will be retried with exponential backoff. Ensure your endpoint is idempotent

​

Events

​

Request headers

​

Response headers

​

Payload structure

{
  "id": "bb7fbf57-1209-4d4e-88d4-0af285a96047",
  "event": "generation.completed",
  "created_at": "2026-01-22T16:07:08.044Z",
  "api_version": "2026-01-05",
  "data": {
    "generation_id": "f53f23ab-c8b6-4e4e-acd5-310a552821d7",
    "status": "succeeded",
    "name": "Room Design",
    "prompt": "Make the sheets in the style of the logo. Make the scene natural",
    "model": "google/nano-banana",
    "credit_cost": 2,
    "output_images": [
      "https://app.babysea.ai/storage/v1/object/public/image_generation/output/f53f23ab-c8b6-4e4e-acd5-310a552821d7/tmpscku3dnk.jpeg"
    ],
    "output_success": 1,
    "output_failed": 0,
    "failure_reason": null,
    "predict_time": 9.043826488,
    "total_time": 9.452142989,
    "created_at": "2026-01-22T16:06:55.588566",
    "completed_at": "2026-01-22T16:07:08.044Z"
  }
}

​

Payload schema

​

Signature verification

const crypto = require('crypto');

function verifyWebhookSignature(req) {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const payload = JSON.stringify(req.body);
  
  // Parse signature header: t=timestamp,v1=signature
  const [, v1Part] = signature.split(',');
  const receivedSig = v1Part.split('=')[1];
  
  // Compute expected signature
  const signedPayload = `${timestamp}.${payload}`;
  const expectedSig = crypto
    .createHmac('sha256', process.env.BABYSEA_WEBHOOK_SECRET)
    .update(signedPayload)
    .digest('hex');
  
  // Verify timestamp is recent (prevent replay attacks)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    return false; // Reject if older than 5 minutes
  }
  
  return receivedSig === expectedSig;
}

import hmac
import hashlib
import time
import os

def verify_webhook_signature(request):
    signature = request.headers.get('X-Webhook-Signature')
    timestamp = request.headers.get('X-Webhook-Timestamp')
    payload = request.get_data(as_text=True)
    
    # Parse signature header
    parts = dict(p.split('=') for p in signature.split(','))
    received_sig = parts.get('v1')
    
    # Compute expected signature
    signed_payload = f"{timestamp}.{payload}"
    expected_sig = hmac.new(
        os.environ['BABYSEA_WEBHOOK_SECRET'].encode(),
        signed_payload.encode(),
        hashlib.sha256
    ).hexdigest()
    
    # Verify timestamp (prevent replay attacks)
    if abs(time.time() - int(timestamp)) > 300:
        return False
    
    return hmac.compare_digest(received_sig, expected_sig)

​

Rate limits

​

Generation

​

Endpoint

​

Handling

• Monitor remaining requests: Check the X-RateLimit-Remaining header to track your usage
• Implement exponential backoff: When rate limited (429 status), wait before retrying with increasing delays
• Use reset timestamp: Check X-RateLimit-Reset to know exactly when to retry
• Queue requests: Implement client-side queuing to stay within rate limits
• Log request IDs: Always log X-Request-ID for debugging failed or rate-limited request