Sommaire
Pourquoi les webhooks posent problème en multi-nœuds
Sur MeshMac, le piège classique est de traiter le webhook sur le seul Mac qui reçoit la requête HTTP : vous perdez alors l’intérêt d’une file partagée et les autres nœuds ne voient ni la tâche ni l’état du build. Deux autres causes dominent en 2026 : des corps JSON non validés (formes inattendues, champs trop longs) qui font planter le parseur ou enfilent des tâches incohérentes, et une authentification absente ou faible qui expose l’URL à la reprise et au spoofing.
- JSON non validé — rejeter tôt les schémas invalides évite d’enfiler du « bruit » et facilite le diagnostic.
- Auth insuffisante — secret Bearer, HMAC ou mTLS selon votre fournisseur ; jamais d’effet de bord avant vérification.
- Dispatch local — après validation, la seule action synchrone doit être l’écriture dans la file centralisée ; l’exécution OpenClaw reste côté workers.
Alignez le webhook sur le même modèle de file de tâches centralisée que dans notre article déploiement unifié et synchronisation de la file sur MeshMac, afin que chaque nœud consomme le même travail et le même état.
Tableau de synthèse : validation, jeton, tâche OpenClaw, notification
Ce tableau sépare les responsabilités : que contrôler avant de faire confiance à la requête, comment prouver l’identité de l’appelant, où OpenClaw récupère le travail, et comment informer l’équipe ou un système tiers — sans dépendre d’un fournisseur précis (Slack, Teams, webhook maison, NATS, Kafka, etc.).
| Couche | Objectif | Implémentation typique |
|---|---|---|
| Validation des entrées | Rejeter tôt les payloads invalides | JSON Schema ou DTO typé ; champs requis : event, dépôt, ref, SHA de commit, clé d’idempotence |
| Jeton / signature | Prouver l’origine de l’appel | Secret Bearer dans Authorization, ou HMAC-SHA256 du corps brut ; comparaison en temps constant |
| Déclenchement OpenClaw | Build partagé sur n’importe quel nœud | Normaliser le payload → un enregistrement de tâche → push vers Redis, SQS ou API centrale que tous les nœuds interrogent |
| Diffusion d’état | Visibilité multi-nœuds et externe | POST HTTPS vers URL d’équipe, topic sur bus de messages, ou webhook entrant compatible chat ; toujours joindre node_id et build_id |
Pour le contexte agents et coordination entre machines, croisez avec collaboration OpenClaw multi-nœuds sur maillage Mac.
Étapes de configuration (ordre recommandé)
On suppose la terminaison TLS devant un reverse proxy et des workers OpenClaw déjà pointés vers un seul backend de file. Les étapes suivantes s’appliquent à tout maillage MeshMac reproductible.
- Publier une route HTTPS unique (ex.
/hooks/openclaw/build). Attribuer un identifiant de corrélation par requête et le renvoyer dans le JSON de réponse pour faciliter les retries côté GitHub, GitLab ou outil interne. - Valider avant tout effet de bord. Parser le JSON, imposer types et longueurs max, refuser les valeurs d’
eventinconnues avec400. N’enfiler la tâche qu’une fois la validation passée. - Vérifier le secret. Pour Bearer : retirer le préfixe
Beareret comparer au secret stocké dans un coffre. Pour HMAC : recalculer sur les octets bruts du corps et comparer avec une primitive typecrypto.timingSafeEqual(ou équivalent). - Enfiler la tâche OpenClaw. Mapper le webhook vers un type de tâche unique (ex.
shared_build) avec idempotence, commit et labels. N’importe quel nœud du maillage peut la réclamer. La sémantique de retry est détaillée dans file de tâches et étapes de retry. - Émettre les notifications d’état. Après enqueue, envoyer un court événement
queuedvers votre adaptateur. Lors des transitions OpenClaw, répéter pourrunning,succeededoufailed. Une interface d’adaptateur unique permet de changer de canal sans toucher au cœur de l’agent. - Répondre vite au client HTTP. Accuser réception avec
202dès que la tâche est durable dans la file. Reporter validation lourde ou fan-out asynchrone pour rester sous les ~10–30 secondes imposées par beaucoup de fournisseurs amont.
Paramètres de référence
| Sujet | Ordre de grandeur | Note d’exploitation |
|---|---|---|
| Timeout HTTP amont | 10–30 s | Garder le handler webhook sous ~5 s ; le travail long reste dans la file |
| Fenêtre d’idempotence | 24–72 h | Évite les builds jumeaux lors des duplications de livraison |
| Notifications sortantes | Timeout 3–5 s, 3 retries | Backoff exponentiel pour DNS ou micro-coupures réseau |
Dépannage : codes HTTP courants
Les émetteurs et proxys interprètent ces codes au pied de la lettre. Utilisez ce tableau pour réduire le temps d’incident.
| Code | Cause probable | Que vérifier |
|---|---|---|
| 400 | JSON mal formé ou schéma refusé | Logs du corps, champs obligatoires, Content-Type et encodage |
| 401 | Jeton Bearer absent ou incorrect | En-tête Authorization, rotation des secrets, montage du coffre sur chaque réplique |
| 403 | Auth OK mais source interdite | Liste d’IP, allowlist d’organisation, environnement (prod vs staging) |
| 404 | Chemin ou règle d’ingress obsolète | Slash final, règles LB, hôte canary vs production |
| 413 | Payload trop volumineux | Limites nginx/CDN ; réduire les diffs ou pièces jointes dans le corps |
| 429 | Quota ou throttle | Limite par source, rafale autorisée, en-têtes de backoff |
| 500 | Exception non gérée dans le handler | Logs applicatifs, dépendances, erreurs client file |
| 502 / 503 | Dépendance indisponible | Joignabilité de la file depuis le service webhook, TLS vers Redis, readiness des pods |
Résumé
Traitez le webhook comme une fine couche de confiance : valider, authentifier, enfiler une seule fois, puis notifier via un adaptateur générique. Ce schéma scale sur MeshMac car seuls la file et les points de notification doivent rester cohérents entre nœuds. Pour aller plus loin : page OpenClaw, liste du blog, accueil Meshmac et centre d’aide pour SSH/VNC avant de louer une capacité Mac dédiée.
Déployer vos webhooks sur de vrais nœuds MeshMac
Vous avez les étapes pour valider, authentifier, enfiler et notifier. Passez à l’exécution sur des Mac Apple Silicon distants avec SSH et VNC : parcourez l’accueil pour comparer les offres, le blog pour les guides cluster, et le centre d’aide pour la connexion — puis louez le nœud adapté à votre équipe sans engagement superflu.