Contrat webhooks HMAC Nexus

Objectif

Ce document fixe le contrat minimal des webhooks entrants Nexus signes HMAC.

Les webhooks HMAC sont destines aux flux serveur-a-serveur qui ne passent ni par une session utilisateur, ni par MFA interactive, ni par OIDC client_credentials.

Endpoint v1

POST /api/webhooks/{source_app}/events

Cet endpoint valide la requete et retourne accepted=true. Il ne declenche pas encore d'action metier destructive ni d'ingestion automatique.

Headers requis

X-Nexus-Tenant-Id: <tenant_uuid>
X-Nexus-Timestamp: <unix_epoch_seconds>
X-Nexus-Signature: sha256=<hex_hmac_sha256>

Message signe

La signature HMAC SHA-256 est calculee sur :

<timestamp>.<tenant_id>.<source_app>.<raw_body>

Exemple pseudo-code :

message = f"{timestamp}.{tenant_id}.{source_app}.".encode("utf-8") + raw_body
signature = "sha256=" + hmac_sha256(secret, message).hexdigest()

Stockage du secret

Le lot v1 reutilise le stockage chiffre existant, sans migration DB :

integration_credentials.category = "webhooks"
integration_credentials.key = "<tenant_id>:<source_app>"
integration_credentials.encrypted_value = <secret chiffre>

Le chiffrement repose sur LLM_CREDENTIALS_ENC_KEY via api.security_utils.

Les secrets bruts ne sont pas stockes dans le depot et ne doivent jamais etre journalises.

Validation

Nexus refuse la requete si :

• le tenant est absent ou inconnu;
• la source {source_app} est absente, inconnue ou inactive dans caller_apps_config;
• le secret webhook n'est pas configure;
• le timestamp sort de la fenetre anti-replay;
• la signature manque, est mal formee ou ne correspond pas.

La tolerance anti-replay est configuree par :

WEBHOOK_HMAC_MAX_SKEW_SECONDS=300

Audit

Les decisions sont journalisees cote serveur avec :

• outcome=accepted|rejected;
• tenant_id;
• source_app;
• raison du refus si applicable;
• prefixe court de signature, jamais la signature complete ni le secret.

Limites v1

• Pas de rotation admin UI dans ce lot.
• Pas de table dediee aux secrets webhook.
• Pas d'action metier automatique apres validation.
• Pas de remplacement d'OIDC M2M ni des tokens MCP/service existants.