Webhooks

Webhooks

Receive real-time notifications when content changes in Contensa.ai. Essential for cache invalidation, static site regeneration, and workflow automation.

Setting Up a Webhook

1

Go to Webhooks

In your project dashboard, click Webhooks in the left sidebar.

2

Click Create Webhook

Enter your endpoint URL — this is the URL Contensa.ai will POST to when events occur.

3

Select events

Choose which events trigger the webhook: content.published, content.updated, content.deleted, or all events.

4

Save and test

Click Save, then use the Test button to send a sample payload to your endpoint.

Event Types

content.published

Fired when a content entry is published or re-published.

content.updated

Fired when a draft entry is saved (not yet published).

content.deleted

Fired when a content entry is permanently deleted.

content.archived

Fired when a content entry is archived.

content-model.updated

Fired when a content model schema is changed.

media.uploaded

Fired when a new media file is uploaded.

Webhook Payload

Every webhook POST request includes a JSON body with this structure:

{
  "event": "content.published",
  "timestamp": "2026-02-23T00:00:00.000Z",
  "projectId": "proj_xxxx",
  "environmentId": "env_xxxx",
  "data": {
    "id": "entry_xxxx",
    "contentTypeId": "type_xxxx",
    "contentTypeSlug": "blog-post",
    "slug": "my-first-post",
    "status": "published",
    "locale": "en-US",
    "updatedAt": "2026-02-23T00:00:00.000Z"
  }
}

Handling Webhooks (Next.js)

Create an API route to receive and process webhook events:

// app/api/webhooks/contensa/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { event, data } = payload;

  if (event === 'content.published') {
    // Revalidate the affected page
    await fetch(`/api/revalidate?path=/blog/${data.slug}`, {
      method: 'POST',
    });
  }

  return NextResponse.json({ received: true });
}

Next.js ISR Cache Invalidation

Use webhooks to trigger on-demand revalidation in Next.js:

// app/api/revalidate/route.ts
import { revalidatePath } from 'next/cache';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const { path } = await req.json();
  revalidatePath(path);
  return NextResponse.json({ revalidated: true, path });
}

Retry Logic

Success

Return a 2xx status code within 10 seconds to acknowledge receipt.

Failure & Retry

If your endpoint returns a non-2xx or times out, Contensa.ai retries up to 3 times with exponential backoff (1min, 5min, 30min).

Best Practices

Always return a 200 response immediately, then process the event asynchronously

Validate the webhook payload before processing

Make your webhook handler idempotent — the same event may be delivered more than once

Log all incoming webhook events for debugging

Use a queue (e.g. BullMQ, SQS) for heavy processing tasks triggered by webhooks