Webhooks and on-demand revalidation: keep your headless site fresh without full rebuilds

Originally published on .

Static and ISR sites are fast because they cache content. That same cache is why your homepage still shows yesterday’s headline after you hit Publish in the CMS.

You do not need a full rebuild every time. Point a webhook at a small API route, verify the signature, then call on-demand revalidation (revalidateTag / revalidatePath in Next.js, or a rebuild hook on Astro/Cloudflare). This guide walks through that pattern with ) and a publicly reachable HTTPS URL for the handler (local tunnels work for testing).

1. Create the webhook in NomaCMS

1. Open your project in .
   
   
   

   URL rules: HTTPS is required in normal setups. The platform rejects private, loopback, and credential-in-URL targets. That protects against SSRF-style misconfiguration.

   
   
   

   
   
   
   2. What each delivery looks like
   

   
   
   

   When an event matches, NomaCMS POSTs JSON to your URL. At send time the body includes at least:

   
   
   
   
   
   • 
     event (for example content.published)
   
   
   • project_uuid
   
   
   • 
     timestamp (ISO 8601)
   
   
   • 
     delivery_id (unique per attempt)
   
   
   
   
   

   If you set a secret, the request includes header X-Webhook-Signature: hex-encoded HMAC-SHA256 of the exact JSON body using that secret.

   
   
   

   Keep your handler fast. Return 2xx quickly. Do heavy work after you acknowledge the request if your framework allows it. Timeouts are short (about 10 seconds on the sender).

   
   
   

   
   
   
   3. Next.js: revalidate on webhook
   

   
   
   

   Tag your CMS fetches so you can clear them by name.
   
   

   
   
   
   
   

   CODE Kopieren

   // Example: fetch with a tag in a Server Component
   
   const posts = await fetch("https://app.nomacms.com/api/...", {
   
     next: { tags: ["cms-posts"] },
   
   })
   
   

   
   
   
   
   
   
   
   

   Or, if you use @nomacms/js-sdk inside a Server Component, wrap data loading so the result participates in Next.js caching and use the same tag strategy your app already uses. The Next.js guide notes revalidate, revalidatePath, and revalidateTag for CMS updates: note on rebuilding when CMS content changes.



2. 
   Cloudflare / Netlify / similar: many platforms expose a “deploy hook” URL. Point the NomaCMS webhook at that URL, or at a thin proxy that checks the signature first.





Signature checking still matters even if the target is a deploy hook, if you can put a small verifier in front.








5. Retries and delivery logs






From the sender:






• Failed network calls and 5xx (and 429) are retried (job tries 3, backoff 30 seconds).


• Most 4xx responses are not retried (your bug, not a blip). Fix the handler, then publish again or wait for the next edit.






In the dashboard (or via GET /api/webhooks/{uuid}/logs / client.webhooks.logs), open delivery logs for the webhook. You will see the event name, URL, HTTP status (or blocked / error), and truncated request/response bodies. Use that when your Route Handler returns 401 or 500.





Docs:


3. (7-day free trial)





Questions welcome in the comments.

Vollständiger Original-Bericht
Ausführliche Details, Code-Beispiele & Hersteller-Stellungnahme auf dev.to.
↗ Original-Artikel auf dev.to lesen