[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]
Slice : [Numéro de la tranche verticale]
Version : 1.0

1. Vue d’ensemble (DOC)

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éclencheurs1/2

Événement	Statut
Création de document	[✅/❌]
Modification de document	[✅/❌]
Publication de document	[✅/❌]
Suppression de document	[✅/❌]

1.3. Événements Sanity déclencheurs2/2

Type de document	Statut
post	[✅/❌]
project	[✅/❌]
page	[✅/❌]
author	[✅/❌]
category	[✅/❌]

2. Configuration (CODE)

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
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. Architecture et flux (DOC)

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	`/ObjectData/cloudflare-workers-objectData.md`
Pipeline CI/CD	Build et déploiement	Infrastructure	[Lien vers docs CI/CD]

4. Contrats d’Entrée/Sortie (SPEC)

4.1. Inputs (payload webhook)

Champ	Type	Description
`transition`	`string`	Type de transition (publish, create, update, delete)
`document`	`object`	Document modifié
`timestamp`	`string`	Timestamp de l’événement

4.2. Outputs (réponse Worker)

Code HTTP	Condition	Description
200	Webhook traité avec succès	Build déclenché ou ignoré (debounce)
401	Signature invalide	Secret incorrect
403	Signature manquante	En-tête manquant
500	Erreur serveur	Erreur interne du Worker

4.3. Side effects

Effet	Description	Fréquence
Déclenchement build	Appel du deploy hook CI/CD	À chaque publication (debounce 2 min)
Lock KV	Pose d’un lock de 2 minutes	À chaque webhook reçu

5. Tests attendus (TEST)

5.1. Tests unitaires

Scénario	Description	Résultat attendu
Validation HMAC-SHA256	Signature correcte vs incorrecte	Validation réussie vs échec
Debouncing KV	Webhooks multiples en 2 min	Premier traité, autres ignorés

5.2. Tests d’intégration

Scénario	Dépendances	Description	Résultat attendu
Flux complet	Sanity → Worker → CI/CD	Publication → Webhook → Build	Site mis à jour
Débouncing	KV + Worker	Publications rapides successives	Un seul build déclenché

5.3. Tests E2E

Scénario	Parcours utilisateur	Description	Résultat attendu
Publication → Rebuild	Sanity Studio → Webhook → Build	Publication d’un article	Nouveau contenu visible après rebuild

6. Intégration (INTÉG)

6.1. Intégration avec les composants

Composant	Type	Rôle	Méthode d’intégration
Sanity Studio	L1	Envoi du webhook	Configuration dans Studio
cms-webhook-receiver	L3	Réception et traitement	HTTP POST endpoint
Pipeline CI/CD	Infrastructure	Build et déploiement	Deploy hook

6.2. Points d’attention

Le secret doit être identique dans Sanity et le Worker
Le debounce KV protège les quotas CI/CD
Les webhooks ne sont déclenchés que sur publish (pas sur les drafts)

6.3. Vérification de cohérence

Le webhook est configuré dans Sanity Studio
Le Worker reçoit et valide les webhooks
Le build est déclenché correctement
Le debounce fonctionne
Les tests E2E passent

7. Sécurité

7.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

7.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.

7.3. Règles de sécurité

✅ Utiliser un secret fort et unique par environnement
✅ Ne jamais logger le secret ou le payload en clair
✅ Rotation régulière du secret (tous les 90 jours)

8. Performance et limites

8.1. Considérations de performance

Aspect	Valeur	Stratégie
Debounce	2 minutes	Protection CI/CD
Timeout webhook	30 secondes	Limite Sanity
Retry automatique	3 tentatives	Sanity native

8.2. Limitations

❌ 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
❌ Le debouncing de 2 minutes peut masquer des publications rapides

9. Débogage et troubleshooting

9.1. Problèmes courants

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

9.2. Logs et monitoring

Côté Sanity :

Sanity Studio → Settings → Webhooks → Delivery logs

Côté Worker L3 :

Cloudflare Worker Logs

9.3. Commandes de debug

# 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"

10. Bonnes pratiques

10.1. Configuration

✅ Utiliser un filtre GROQ pour limiter les webhooks
✅ Désactiver “Include drafts” pour éviter les webhooks inutiles
✅ Utiliser un secret fort et unique par environnement

10.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
✅ Signaler immédiatement tout échec de build

11. Évolutions et roadmap

11.1. Améliorations planifiées

[Évolution 1 : ex. Filtrage avancé par type de document]
[Évolution 2 : ex. Notification Slack/Teams en cas d’échec]

11.2. Limitations connues

❌ Les webhooks ne sont pas rétroactifs
❌ Le payload Sanity ne contient pas toutes les métadonnées

12. Ressources liées

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

13. Historique des modifications

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