Webhooks

Status: Complete — All content endpoints trigger webhooks.

Overview

The webhook service is fully integrated with all content CRUD and publish endpoints:

1. Service: apps/api/src/services/webhook.ts
2. Routes: apps/api/src/routes/admin/webhooks.ts
3. Repositories: @tentocms/db (WebhookRepository, WebhookDeliveryRepository)

Available Functions

triggerWebhooks()

Triggers webhooks for a content event. This function:

• Finds all active webhooks subscribed to the event
• Creates delivery records in the database
• Dispatches async HTTP requests via ctx.waitUntil()

Signature:

triggerWebhooks(
  db: D1Database,
  projectId: string,
  event: WebhookEvent,
  data: unknown,
  ctx: ExecutionContext
): Promise<void>

generateSignature()

Generates HMAC-SHA256 signature for payload verification.

processWebhookRetries()

Processes failed webhook deliveries with exponential backoff. Called by cron handler.

Endpoint → Event Mapping

Pages (apps/api/src/routes/pages.ts)

Not triggered for: autosave (too frequent, not a deliberate save), schedule/unschedule (no content change, scheduling metadata only).

Collection Items (apps/api/src/routes/collection-items.ts)

Not triggered for: autosave (too frequent, not a deliberate save), schedule/unschedule (no content change, scheduling metadata only).

Media (apps/api/src/routes/media.ts)

Not triggered for: metadata update (PUT /admin/media/:id), move (POST /admin/media/:id/move), folder rename (PUT /admin/media/folders/:name) — no matching event types defined for these operations.

Available Webhook Events

All events are defined in @tentocms/shared:

• page.created
• page.updated
• page.published
• page.unpublished
• page.deleted
• collection_item.created
• collection_item.updated
• collection_item.published
• collection_item.unpublished
• collection_item.deleted
• media.uploaded
• media.deleted

Webhook Payload Structure

All webhooks receive this payload structure:

{
  event: 'page.published',
  timestamp: '2024-01-15T10:30:00.000Z',
  data: {
    // The actual content data (page, collection item, media, etc.)
  }
}

HTTP Headers

Webhook requests include these headers:

• Content-Type: application/json
• X-Webhook-Signature: sha256={hmac_signature}
• X-Webhook-Event: {event_type}
• X-Webhook-Delivery-Id: {delivery_uuid}
• User-Agent: TentoCMS-Webhook/1.0
• Any custom headers configured on the webhook

Retry Logic

Failed deliveries are automatically retried with exponential backoff:

1. 1 minute
2. 5 minutes
3. 15 minutes
4. 1 hour
5. 4 hours

After 5 failed attempts, the delivery is marked as exhausted.

Testing

Use the test endpoint to verify webhook configuration:

POST /api/v1/admin/webhooks/:id/test

This sends a test page.updated event with sample data.

Security

• Secrets are only shown on webhook creation and regeneration
• Secrets are masked in list views (shows last 8 chars)
• All webhook operations require developer role
• HMAC-SHA256 signatures allow receivers to verify authenticity

Performance & Resilience

• Webhook delivery is async via ctx.waitUntil() — doesn't block API responses
• All triggerWebhooks() calls are wrapped in try/catch — webhook failures never break content operations
• Bulk operations fire webhooks in parallel via Promise.allSettled
• 30 second timeout per delivery attempt
• Response body captured up to 10KB
• Cron handler processes retries every minute