title: "Addendum 13 — Enabling Hooks · Webhooks & Event Bus — Août 2026" date: "2026-08-31" author: "ATLAS Engine"

Addendum 13 — Enabling Hooks · Webhooks & Event Bus

WS10 — Extensibilité de la plateforme | Août 2026

1. Vue d'ensemble

Le workstream WS10 introduit un système de hooks complet qui permet aux intégrations tierces et aux futures lignes de produits (devises, VM, Office 365, applications personnalisées) de se connecter à la plateforme via des webhooks, sans nécessiter de réarchitecture.

2. Architecture

2.1 Event Bus

Bus d'événements interne basé sur eventemitter2 avec prise en charge des caractères génériques (contact.*).

30 événements de plateforme organisés en 6 catégories :

Catégorie	Événements
CRM	`contact.created/updated/deleted`, `deal.created/updated/won/lost`, `organization.created/updated`
Communication	`message.sent/received`, `call.started/ended`, `sms.sent/received`
Billing	`billing.charge/topup/plan_changed`
Platform	`user.created/login/role_changed`, `deploy.promoted/rolledback`
AI	`agent.task_completed`, `agent.skill_executed`
Extensibility	`currency.rate_updated`, `vm.provisioned/terminated`, `office365.synced`, `custom`

2.2 Livraison des webhooks

Signature HMAC-SHA256 avec secret par webhook (en-tête X-Atlas-Signature)
Nouvelle tentative automatique : 3 essais (1s → 5s → 15s)
Journaux complets : chaque livraison est enregistrée (succès et échecs)
Délai d'expiration : 10s par livraison

3. Endpoints API

Méthode	Endpoint	Description
`GET`	`/api/v1/hooks/events`	Catalogue des 30 événements disponibles
`GET`	`/api/v1/hooks/webhooks?orgId=`	Lister les webhooks d'une organisation
`POST`	`/api/v1/hooks/webhooks`	Enregistrer un webhook
`PUT`	`/api/v1/hooks/webhooks/:id`	Modifier un webhook
`DELETE`	`/api/v1/hooks/webhooks/:id`	Supprimer un webhook
`POST`	`/api/v1/hooks/webhooks/:id/regenerate-secret`	Regénérer le secret HMAC
`POST`	`/api/v1/hooks/webhooks/:id/ping`	Envoyer un ping de test
`GET`	`/api/v1/hooks/webhooks/:id/deliveries`	Journal des livraisons
`POST`	`/api/v1/hooks/emit`	Émettre un événement manuellement

4. Stockage

Deux tables créées automatiquement au démarrage (DDL onModuleInit) :

`atlas.webhooks`

id UUID, org_id UUID, name, url, events TEXT[], secret, active, horodatages
Index GIN sur events pour des recherches rapides

`atlas.webhook_deliveries`

id UUID, webhook_id FK, event, url, request_body, response_status, response_body, success, attempt_number, delivered_at
Suppression en cascade avec le webhook parent

5. Cas d'utilisation

Intégration Zapier/Make

Enregistrer un webhook : POST /hooks/webhooks avec { events: ["deal.won"], url: "https://hooks.zapier.com/..." }
Lorsqu'une transaction est conclue, Zapier reçoit automatiquement la charge utile signée
Vérifier la signature HMAC pour authentifier la source

Surveillance interne

Webhook vers Slack : { events: ["deploy.promoted", "deploy.rolledback"] }
Notifications automatiques à chaque déploiement

6. Commit & Déploiement

Commit : aa86613 — feat(WS10): Enabling Hooks — event bus, webhook subscriptions, HMAC delivery + retry, delivery logs
Fichiers : src/modules/hooks/{hooks.module.ts, hooks.controller.ts, hooks.service.ts, event-bus.service.ts}