Webhook Strapi 5 : invalider les tags de cache Vercel pour Next.js

Un webhook Strapi 5 peut appeler l’API edge‑cache de Vercel pour purger les tags de cache chaque fois qu’un contenu est créé, mis à jour ou publié, assurant que vos pages Next.js restent à jour sans redéploiement complet. Vous trouverez ci‑dessous un guide complet couvrant la configuration du webhook, la gestion sécurisée, l’attribution des tags dans Next.js et l’invalidation des tags Vercel.

Vue d’ensemble du flux de travail

1. Attribuer des tags de cache dans Next.js – chaque page qui dépend d’une entrée Strapi ajoute un Vercel-Cache-Tag (via cacheTag).
2. Configurer un webhook Strapi – écouter les événements entry.update et entry.publish pour les types de contenu concernés.
3. Créer une route API Next.js sécurisée – reçoit le payload du webhook, le vérifie, puis appelle le point de terminaison edge‑cache/invalidate‑by‑tags de Vercel.
4. Utiliser éventuellement Revisionary – si vous avez besoin de tags par version, Revisionary peut fournir l’ID de version de l’entrée pour créer des tags uniques.

Le résultat est une revalidation à la demande : lorsqu’un éditeur met à jour un article dans Strapi, le tag de cache de la page Next.js associée est invalidé et la prochaine requête récupère des données fraîches.

1. Taguer les pages Next.js avec cacheTag

Next.js 15 (et les versions 13/14 précédentes) propose la fonction cacheTag pour attacher un ou plusieurs tags à une réponse mise en cache. Le tag est envoyé dans l’en‑tête de réponse Vercel-Cache-Tag, que le CDN de Vercel stocke.

// app/articles/[slug]/page.tsx
import { cacheTag } from 'next/cache';
import { fetchArticle } from '@/lib/api';

export default async function ArticlePage({ params }: { params: { slug: string } }) {
  'use server';

  // Taguer la réponse avec l’ID de l’article – utile pour l’invalidation
  cacheTag(`article-${params.slug}`);

  const article = await fetchArticle(params.slug);
  return (
    <article>
      <h1>{article.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: article.body }} />
    </article>
  );
}

Lorsque la page est rendue, Next.js ajoute Vercel-Cache-Tag: article‑my‑post à la réponse. Toute requête qui passe par le CDN de Vercel stocke la réponse sous ce tag.

1.1 Plusieurs tags

Si une page combine plusieurs sources de contenu (par exemple, le profil d’un auteur + l’article), vous pouvez ajouter plusieurs tags :

cacheTag(['article-123', 'author-45']);

2. Configuration du webhook Strapi 5

Strapi 5 vous permet de définir des valeurs par défaut globales pour les webhooks dans ./config/server.js (ou server.ts). Définissez un token bearer pour l’authentification et pointez le webhook vers une route API Next.js.

// config/server.js
module.exports = {
  webhooks: {
    defaultHeaders: {
      Authorization: `Bearer ${process.env.WEBHOOK_TOKEN}`,
    },
    // Optionnel : vérifier les signatures du payload avec X‑Webhook‑Signature
  },
};

2.1 Créer le webhook dans l’interface d’administration

1. Settings → Webhooks → Create new webhook
2. URL : https://my-next-app.vercel.app/api/strapi-revalidate
3. Events : sélectionnez Entry.update et Entry.publish pour les types de contenu que vous souhaitez invalider (par exemple, Article). Vous pouvez également ajouter Entry.delete si vous voulez purger les pages supprimées.
4. Headers : l’en‑tête Authorization est ajouté automatiquement à partir de defaultHeaders.
5. Save.

Strapi enverra désormais un POST JSON à l’URL indiquée chaque fois que les événements sélectionnés se produisent.

3. Gestion sécurisée du webhook Next.js

Créez une route API (ou un Route Handler dans l’App Router) qui vérifie la requête et appelle l’API edge‑cache de Vercel.

// src/app/api/strapi-revalidate/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { Vercel } from '@vercel/sdk';

export async function POST(req: NextRequest) {
  // 1️⃣ Vérifier le token bearer
  const auth = req.headers.get('authorization');
  if (auth !== `Bearer ${process.env.WEBHOOK_TOKEN}`) {
    return new NextResponse('Unauthorized', { status: 401 });
  }

  // 2️⃣ Analyser le payload Strapi
  const payload = await req.json();
  const { event, entry } = payload;

  // Nous ne nous intéressons qu’aux mises à jour et aux publications
  if (!['entry.update', 'entry.publish'].includes(event)) {
    return new NextResponse('Ignored event', { status: 200 });
  }

  // 3️⃣ Construire le tag de cache – correspondre au tag utilisé dans Next.js
  // En supposant que l’ID de l’entrée soit le slug ou un ID numérique
  const tag = `article-${entry.id}`; // ajustez si vous utilisez le slug

  // 4️⃣ Appeler l’API Vercel edge‑cache invalidate‑by‑tags
  const vercel = new Vercel({
    bearerToken: process.env.VERCEL_BEARER_TOKEN,
  });

  try {
    await vercel.edgeCache.invalidateByTags({
      projectIdOrName: process.env.VERCEL_PROJECT,
      tags: [tag],
    });
    return new NextResponse('Cache invalidated', { status: 200 });
  } catch (err) {
    console.error('Vercel invalidate error', err);
    return new NextResponse('Failed to invalidate', { status: 500 });
  }
}

Points clés de sécurité

• Bearer token – correspond au token défini dans les defaultHeaders de Strapi.
• Vérification HMAC optionnelle – Strapi peut envoyer un en‑tête X‑Webhook‑Signature ; vérifiez‑le avec un secret partagé pour une protection supplémentaire.
• Limiter les événements autorisés – le gestionnaire ignore explicitement les événements non pertinents.

3.1 Variables d’environnement

Ajoutez les suivantes à votre projet Vercel :

• WEBHOOK_TOKEN – secret partagé pour Strapi ↔ Next.js.
• VERCEL_BEARER_TOKEN – token généré dans le tableau de bord Vercel (Settings → Tokens).
• VERCEL_PROJECT – le nom ou l’ID de votre projet Vercel.

4. Utilisation de Revisionary pour des tags sensibles à la version (optionnel)

Si vous versionnez le contenu avec le plugin Revisionary, vous pouvez ne vouloir invalider le cache que lorsqu’une version précise est publiée. Revisionary stocke chaque version dans le journal d’audit et propose une content API qui renvoie les métadonnées de version.

// Exemple : récupérer l’ID de la version publiée la plus récente
const res = await fetch(`${process.env.STRAPI_URL}/api/articles/${entry.id}?populate=revision`,
  { headers: { Authorization: `Bearer ${process.env.STRAPI_ADMIN_TOKEN}` } }
);
const data = await res.json();
const versionId = data.data.attributes.revision?.latest?.id;
const tag = `article-${entry.id}-v${versionId}`;

Puis utilisez le même tag dans votre page Next.js :

// Puis utilisez le même tag dans votre page Next.js :
cacheTag(`article-${slug}-v${process.env.NEXT_PUBLIC_VERSION_ID}`);

Cette approche vous permet de conserver les versions en cache anciennes pendant que la nouvelle version est en cours de révision, et de ne purger le tag qu’une fois la révision finalement publiée.

5. Tester le flux de bout en bout

1. Déployer l’application Next.js – assurez‑vous que la route /api/strapi-revalidate est accessible.
2. Créer un article test dans Strapi.
3. Ouvrir la page de l’article dans le navigateur ; inspectez les en‑têtes de réponse (DevTools → Network) – vous devez voir Vercel-Cache-Tag: article-<id>.
4. Mettre à jour l’article dans l’interface d’administration de Strapi.
5. Vérifier les logs du webhook (/admin/settings/webhooks → « History ») – une réponse 200 indique que le gestionnaire a été exécuté.
6. Actualiser la page – le CDN doit servir une réponse fraîche (vous verrez une nouvelle valeur d’en‑tête x-vercel-cache ou un MISS).

Si le tag de cache n’est pas invalidé, vérifiez :

• Que l’en‑tête Authorization correspond.
• Que le token Vercel possède le scope Edge Cache: Invalidate.
• Que la chaîne du tag correspond exactement à celle envoyée par Next.js (sensible à la casse).

6. Problèmes courants et dépannage

7. Structure complète de l’exemple de dépôt

my-next-app/
├─ app/
│  ├─ api/
│  │  └─ strapi-revalidate/
│  │     └─ route.ts   ← gestionnaire du webhook
│  └─ articles/[slug]/
│     └─ page.tsx      ← utilisation de cacheTag
├─ .env.local
│  ├─ WEBHOOK_TOKEN=…
│  ├─ VERCEL_BEARER_TOKEN=…
│  └─ VERCEL_PROJECT=my-next-app
└─ package.json

Déployez avec vercel ou via le tableau de bord Vercel ; les variables d’environnement sont injectées automatiquement.

8. Quand privilégier l’invalidation par tags Vercel plutôt que la revalidation ISR

Si vous utilisez déjà le edge‑cache de Vercel pour les assets statiques ou que vous avez de nombreux déploiements de preview, l’invalidation basée sur les tags est le choix le plus robuste.

9. Résumé

• Attribuer des tags de cache dans Next.js avec cacheTag.
• Configurer un webhook Strapi 5 qui se déclenche sur entry.update et entry.publish.
• Construire une route API sécurisée dans Next.js qui vérifie le token bearer et appelle l’endpoint edge‑cache/invalidate‑by‑tags de Vercel.
• Optionnellement enrichir les tags avec les IDs de version Revisionary pour un contrôle fin.
• Tester le flux, surveiller les pièges courants, et profiter d’une fraîcheur du cache instantanée sans redéploiement complet.

En couplant Strapi et Vercel, vous obtenez la performance de la génération statique tout en conservant l’agilité éditoriale d’un CMS headless.

Lectures complémentaires

• Référence des webhooks Strapi – https://docs.strapi.io/cms/backend-customization/webhooks
• API edge‑cache Vercel – https://vercel.com/docs/rest-api/edge-cache/invalidate-by-tag
• Documentation des tags de cache Next.js – https://nextjs.org/docs/app/api-reference/functions/cacheTag
• Documentation Revisionary – <./docs/getting-started/requirements>

Bon codage !