Webhooks Guide

Receive real-time notifications when content changes in MeshBase. Perfect for triggering builds, invalidating caches, and keeping your site synchronized.

What are Webhooks?

Webhooks are HTTP callbacks that MeshBase sends to your server when specific events occur. When content is published, updated, or deleted, MeshBase can automatically notify your application.

Common Use Cases

  • →Rebuild static sites when content is published (Next.js, Astro, etc.)
  • →Invalidate CDN caches when content updates
  • →Revalidate Next.js pages with on-demand ISR
  • →Sync content to search engines or third-party services
  • →Send notifications to Slack, Discord, or email

Setting Up Webhooks

1. Create a webhook endpoint

In your MeshBase dashboard:

  1. Go to Project Settings
  2. Click the Webhooks tab
  3. Click Add Webhook
  4. Enter your endpoint URL (e.g., https://yoursite.com/api/webhook)
  5. Select events to listen for
  6. Click Save

2. Available Events

  • entry.create - New content entry created
  • entry.update - Content entry updated
  • entry.delete - Content entry deleted
  • entry.publish - Content entry published
  • entry.unpublish - Content entry unpublished

Webhook Payload

MeshBase sends a JSON payload to your endpoint:

{
  "event": "entry.publish",
  "timestamp": "2026-02-19T10:30:00.000Z",
  "data": {
    "id": "abc123",
    "collectionType": "blog-posts",
    "title": "My Blog Post",
    "slug": "my-blog-post",
    "publishedAt": "2026-02-19T10:30:00.000Z"
  },
  "project": {
    "id": "proj_xyz789",
    "name": "My Project"
  }
}
🔒

Verify Webhook Signatures

Always verify webhook signatures to ensure requests come from MeshBase. Check the X-MeshBase-Signature header.

Next.js On-Demand Revalidation

Revalidate specific pages when content changes.

Create webhook route

Create app/api/revalidate/route.ts:

import { revalidatePath } from 'next/cache';
import { NextRequest } from 'next/server';

export async function POST(request: NextRequest) {
  // Verify secret token
  const secret = request.nextUrl.searchParams.get('secret');
  if (secret !== process.env.REVALIDATE_SECRET) {
    return Response.json({ error: 'Invalid token' }, { status: 401 });
  }

  const body = await request.json();
  
  // Revalidate based on content type
  if (body.data.collectionType === 'blog-posts') {
    // Revalidate blog list
    revalidatePath('/blog');
    
    // Revalidate specific post
    if (body.data.slug) {
      revalidatePath(`/blog/${body.data.slug}`);
    }
  }

  return Response.json({ 
    revalidated: true, 
    now: Date.now() 
  });
}

Configure webhook in MeshBase

Set webhook URL to: https://yoursite.com/api/revalidate?secret=YOUR_SECRET

Trigger Vercel/Netlify Deploys

Automatically rebuild your site when content is published.

Option 1: Direct Deploy Hook

Use Vercel/Netlify's deploy hook URL directly:

  1. In Vercel/Netlify, create a Deploy Hook
  2. Copy the webhook URL
  3. Add it to MeshBase webhooks settings
  4. Select entry.publish event
⚠️

Rate Limit Aware

Deploying on every publish can be expensive. Consider debouncing or only deploying on specific content types.

Option 2: Custom Deploy Trigger

Add logic to control when deploys happen:

// app/api/deploy/route.ts
export async function POST(request: NextRequest) {
  const body = await request.json();
  
  // Only deploy for specific content types
  const deployTypes = ['blog-posts', 'pages'];
  if (!deployTypes.includes(body.data.collectionType)) {
    return Response.json({ skipped: true });
  }

  // Trigger Vercel deploy
  await fetch(process.env.VERCEL_DEPLOY_HOOK!, {
    method: 'POST'
  });

  return Response.json({ deployed: true });
}

Testing Webhooks

Local Development with ngrok

Test webhooks locally using ngrok:

# Install ngrok
npm install -g ngrok

# Start your dev server
npm run dev

# In another terminal, expose it
ngrok http 3000

Use the ngrok URL (e.g., https://abc123.ngrok.io/api/webhook) in MeshBase webhook settings.

Manual Testing

Test your webhook endpoint with curl:

curl -X POST https://yoursite.com/api/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "event": "entry.publish",
    "timestamp": "2026-02-19T10:30:00.000Z",
    "data": {
      "id": "test123",
      "collectionType": "blog-posts",
      "slug": "test-post"
    }
  }'

Best Practices

  • ✓
    Always verify signatures

    Check the signature header to prevent unauthorized requests

  • ✓
    Respond quickly

    Return 200 OK within 5 seconds. Do heavy processing async

  • ✓
    Handle retries gracefully

    Make your endpoint idempotent. MeshBase retries failed webhooks

  • ✓
    Log webhook events

    Keep logs for debugging and auditing

  • ✓
    Use HTTPS

    MeshBase only sends webhooks to HTTPS endpoints

Next Steps