Webhooks

ObjectOS utilise un modèle d'outbox persistant pour les webhooks sortants. Lorsque le plugin de webhooks est activé, les changements métier mettent en file d'attente une ligne de livraison, et un distributeur en arrière-plan la livre avec des nouvelles tentatives — de sorte qu'un récepteur lent ou indisponible ne bloque jamais la transaction d'origine.

Activer les webhooks

Les webhooks sont une capacité optionnelle. L'image ObjectOS déployée doit inclure @objectstack/plugin-webhooks, et l'artefact applicatif doit enregistrer des abonnements de webhooks (généralement sous forme d'enregistrements d'un objet sys_webhook).

Une fois activés, deux objets apparaissent dans la Console :

Sémantique de livraison

• Au moins une fois. Une livraison peut être retentée après un échec transitoire ; les récepteurs doivent être idempotents.
• Persistante. Les livraisons survivent aux redémarrages d'ObjectOS car elles sont stockées dans la base de données métier.
• Partitionnée. Chaque worker du distributeur revendique une partition de l'outbox, de sorte que les déploiements peuvent mettre à l'échelle horizontalement la distribution sans double livraison.
• Nouvelles tentatives bornées. Les livraisons échouées sont retentées avec un délai progressif jusqu'à un plafond configurable ; les lignes épuisées restent dans sys_webhook_delivery pour inspection.

Signature

Chaque livraison comporte des en-têtes d'identification afin que les récepteurs puissent l'acheminer, la dédupliquer et la vérifier :

X-Objectstack-Event:     <event type, e.g. data.record.created>
X-Objectstack-Delivery:  <delivery id — use as your idempotency key>
X-Objectstack-Attempt:   <attempt number, starting at 1>

Lorsqu'un abonnement de webhook possède un secret, ObjectOS signe également chaque requête :

X-Objectstack-Signature: sha256=<hex hmac>

La signature est HMAC-SHA256(secret, body), calculée sur le corps brut de la requête. Vérifiez-la côté récepteur avant de faire confiance à la charge utile :

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(body, signatureHeader, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(body).digest('hex');
  return timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}

Faites tourner les secrets en créant un nouvel abonnement avec le nouveau secret, en exécutant les deux pendant une fenêtre de transition, puis en désactivant l'ancien.

Attentes côté récepteur

• Répondez avec un 2xx en quelques secondes. Une réponse 408, 429 ou 5xx (ou un délai d'attente / une erreur de transport) est retentable et donne lieu à une nouvelle tentative avec délai progressif. Tout autre 4xx est traité comme un échec permanent et déplacé vers dead sans nouvelle tentative.
• Le distributeur ne marque pas une livraison comme réussie tant qu'il ne reçoit pas un 2xx ; ainsi, un récepteur défaillant conserve la ligne dans sys_webhook_delivery pour inspection ou nouvelle livraison.
• Soyez idempotent — dédupliquez sur l'en-tête X-Objectstack-Delivery (l'identifiant de livraison) ou sur votre propre identifiant d'événement dans la charge utile.

Gestion des échecs

Lorsqu'une erreur survient :

1. Consultez la ligne dans sys_webhook_delivery — status, response_code, response_body et attempts y sont enregistrés.
2. Vérifiez l'accès réseau sortant d'ObjectOS vers le récepteur.
3. Si le récepteur a été modifié de façon permanente, mettez à jour l'URL de l'abonnement et relivrez la ligne depuis la Console.
4. Pour l'analyse des incidents, les journaux d'audit (sys_audit_log) capturent les modifications d'abonnement mais pas les charges utiles — celles-ci restent dans l'outbox.

Conseils opérationnels

• Ne placez pas de secrets dans les URL de webhook (les chaînes de requête sont journalisées).
• Utilisez un nom d'hôte de récepteur dédié afin de pouvoir délester la charge en le bloquant en périphérie sans affecter l'application principale.
• Surveillez le retard du distributeur — un outbox qui grossit signifie généralement que le récepteur est dégradé.