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, apps custom) de se brancher à la plateforme via des webhooks, sans re-architecture.

2. Architecture

2.1 Event Bus

Bus d’événements interne basé sur eventemitter2 avec support wildcard (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 Webhook Delivery

HMAC-SHA256 signing avec secret par webhook (header X-Atlas-Signature)
Retry automatique : 3 tentatives (1s → 5s → 15s)
Logs complets : chaque delivery est enregistrée (succès + échecs)
Timeout : 10s par delivery

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 org
`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 test ping
`GET`	`/api/v1/hooks/webhooks/:id/deliveries`	Journal des deliveries
`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, timestamps
Index GIN sur events pour lookups rapides

`atlas.webhook_deliveries`

id UUID, webhook_id FK, event, url, request_body, response_status, response_body, success, attempt_number, delivered_at
Cascade delete 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/..." }
Quand un deal est gagné, Zapier reçoit automatiquement le payload signé
Vérifier la signature HMAC pour authentifier la source

Monitoring interne

Webhook vers Slack : { events: ["deploy.promoted", "deploy.rolledback"] }
Notifications automatiques sur 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}