[Nom du Webhook Sanity]

Documentation technique

Type de ressource : Configuration Webhook Sanity
Emplacement : Sanity Studio → Settings → Webhooks
Statut : [Actif / Déprécié / En développement]

1. Vue d’ensemble

1.1. Description

[Description concise de ce que ce webhook déclenche dans l’écosystème]

1.2. Objectif

[Objectif principal : ex. déclencher un rebuild du site lors de la publication]
[Bénéfice pour le workflow éditorial]

1.3. Événements Sanity déclencheurs

Création de document : [✅/❌]
Modification de document : [✅/❌]
Publication de document : [✅/❌]
Suppression de document : [✅/❌]
Types de documents concernés : [Liste : post, project, page, author, category, etc.]

2. Configuration dans Sanity Studio

2.1. Paramètres du webhook1/2

Champ	Valeur	Description
Name	[Nom du webhook]	Nom lisible pour l’identification
URL	`https://[worker-name].[subdomain].workers.dev`	URL du Worker L3 qui reçoit le webhook
HTTP Method	`POST`	Méthode HTTP utilisée
Content Type	`application/json`	Format du payload

2.1. Paramètres du webhook2/2

Champ	Valeur	Description
Secret	[Valeur du secret]	Secret pour validation HMAC-SHA256 (stocké en env)
Events	[Liste des événements]	Ex: `publish.create`, `publish.update`, `publish.delete`
Include drafts	[✅/❌]	Inclure ou non les sauvegardes de brouillons
Filter	[Expression GROQ]	Filtre pour limiter les documents déclencheurs

2.2. Filtre GROQ (si applicable)

_type in ["post", "project", "page", "author", "category"]

Rationale : [Expliquer pourquoi ce filtre est nécessaire]

2.3. Payload envoyé par Sanity

{
  "transactionId": "abc123",
  "transition": "publish",
  "documentId": "post-123",
  "document": {
    "_id": "post-123",
    "_type": "post",
    "title": "Mon article",
    "slug": { "current": "mon-article" },
    "status": "published",
    "publishedAt": "2026-09-03T10:00:00Z"
  },
  "previousRevision": "rev-456",
  "currentRevision": "rev-789",
  "timestamp": "2026-09-03T10:00:00Z"
}

2.4. En-têtes HTTP envoyés

En-tête	Description
`Content-Type`	`application/json`
`x-sanity-signature`	`t=1693735200,v1=abc123...` (timestamp + signature HMAC-SHA256)
`x-sanity-webhook-id`	ID unique du webhook
`User-Agent`	`Sanity-webhook/1.0`

3. Flux et intégration

3.1. Diagramme de flux

[Sanity Content Lake]
     │  (événement : publish, create, update, delete)
     ▼
[HTTP POST vers URL du webhook]
     │
     ▼
[Worker L3 : cms-webhook-receiver]
     │  • Validation HMAC-SHA256
     │  • Debouncing KV
     │  • Déclenchement du build
     ▼
[Hébergeur / CI/CD]
     │  • Build SSG Astro
     │  • Régénération index Pagefind
     │  • Déploiement Cloudflare Pages
     ▼
[Site mis à jour]

3.2. Composants impliqués

Composant	Rôle	Couche	Documentation
Webhook Sanity	Envoi des notifications d’événements	L1	Ce document
`cms-webhook-receiver`	Réception, validation et traitement	L3	`/L3_Backend/cloudflare/workers/cms-webhook-receiver.md`
Pipeline CI/CD	Build et déploiement	Infrastructure	[Lien vers docs CI/CD]

4. Sécurité

4.1. Mécanismes de sécurité

Mécanisme	Implémentation	Rationale
Validation HMAC-SHA256	Signature cryptographique du payload	Garantit l’authenticité et l’intégrité
Secret stocké en env	`wrangler secret put` côté Worker L3	Jamais dans le code source
HTTPS obligatoire	Cloudflare force TLS	Chiffrement en transit
Filtre GROQ	Limitation des documents déclencheurs	Évite les webhooks inutiles

4.2. Gestion du secret

Côté Sanity : Le secret est configuré dans l’interface Studio lors de la création du webhook.

Côté Worker L3 : Le secret est injecté via wrangler secret put :

wrangler secret put SANITY_WEBHOOK_SECRET --env production
wrangler secret put SANITY_WEBHOOK_SECRET --env staging

Règle : Le secret doit être identique des deux côtés.

5. Débogage et troubleshooting

5.1. Problèmes courants

Symptôme	Cause probable	Solution
Webhook non reçu	URL incorrecte ou firewall	Vérifier l’URL dans Sanity et les logs du Worker L3
“Signature invalide” (côté Worker)	Secret incorrect ou payload modifié	Vérifier que le secret est identique dans Sanity et le Worker
Build non déclenché	Filtre Sanity trop restrictif	Vérifier le filtre GROQ dans la configuration
Webhooks en cascade	Pas de debouncing côté Worker	Vérifier la configuration KV dans le Worker L3

5.2. Logs et monitoring

Côté Sanity :

Sanity Studio → Settings → Webhooks → Delivery logs
Vérifier les tentatives de livraison et les réponses HTTP

Côté Worker L3 :

Cloudflare Worker Logs (voir /L3_Backend/cloudflare/workers/cms-webhook-receiver.md)

5.3. Tests manuels

# Test de validation de signature (avec payload factice)
PAYLOAD='{"test": "data"}'
TIMESTAMP=$(date +%s)
SECRET="your-secret"
SIGNATURE=$(echo -n "${TIMESTAMP}.${PAYLOAD}" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST "https://[worker-url]" \
  -H "Content-Type: application/json" \
  -H "x-sanity-signature: t=${TIMESTAMP},v1=${SIGNATURE}" \
  -d "$PAYLOAD"

6. Bonnes pratiques

6.1. Configuration

✅ Utiliser un filtre GROQ pour limiter les webhooks aux documents pertinents
✅ Désactiver “Include drafts” pour éviter les webhooks inutiles
✅ Utiliser un secret fort et unique par environnement (production/staging)
✅ Documenter les changements de configuration dans ce fichier

6.2. Workflow éditorial

✅ Publier les modifications par lots plutôt qu’une par une
✅ Vérifier que le build a bien été déclenché après publication
✅ Ne pas modifier la configuration du webhook sans validation technique
✅ Signaler immédiatement tout échec de build après publication

6.3. Considérations de performance

⚠️ Les webhooks ne sont déclenchés que sur publish (pas sur les sauvegardes de draft)
⚠️ Le Worker L3 implémente un debouncing de 2 minutes pour protéger les quotas CI/CD
✅ Les builds SSG peuvent prendre plusieurs minutes selon le volume de contenu

7. Évolutions et roadmap

7.1. Améliorations planifiées

[Évolution 1 : ex. Filtrage avancé par type de document]
[Évolution 2 : ex. Notification Slack/Teams en cas d’échec]
[Évolution 3 : ex. Rejeu manuel des webhooks échoués]

7.2. Limitations connues

❌ Les webhooks ne sont pas rétroactifs (pas de rejeu automatique en cas d’échec)
❌ Le payload Sanity ne contient pas toutes les métadonnées (seulement le document modifié)
❌ Le debouncing de 2 minutes peut masquer des publications rapides successives

8. Ressources liées

Documentation Sanity : Webhooks
Worker L3 : /L3_Backend/cloudflare/workers/cms-webhook-receiver.md
DAT L1 : §4.9.3 - Alerting Webhook & Opérations
DAT L2 : §7 - Pipeline de Déploiement et d’Invalidation
DAT L3 : §5.2 - Worker cms-webhook-receiver

9. Historique des modifications

Date	Version	Description	Auteur
YYYY-MM-DD	1.0	Création initiale	[Nom]
YYYY-MM-DD	1.1	[Modification]	[Nom]