[Nom du Webhook Sanity]

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éclencheurs

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

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

---

2. Configuration (CODE)

2.1. Paramètres du webhook

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