Skip to Content

API Webhooks

Les webhooks permettent de recevoir des notifications en temps réel lorsqu’un événement se produit dans ton tenant. Auris envoie des requêtes HTTP POST à ton endpoint configuré avec un payload JSON signé.

Tous les endpoints nécessitent le header x-tenant.


Gestion des Webhooks

GET/api/webhooksRequires: manage:webhooks

Liste tous les webhooks configurés pour le tenant.

Réponse de succès

{ "ok": true, "data": [ { "id": "wh_abc123", "url": "https://your-app.com/webhooks/auris", "events": ["user.created", "login.success"], "isActive": true, "failureCount": 0, "createdAt": "2025-01-01T00:00:00Z" } ] }

POST/api/webhooksRequires: manage:webhooks

Crée un nouveau webhook. Retourne le secret de signature — cette valeur n’est visible qu’une seule fois à la création.

Corps de la requête

{ "url": "https://your-app.com/webhooks/auris", "events": ["user.created", "user.updated", "login.failed"], "description": "Webhook principal pour la synchronisation utilisateurs" }

Utilise "events": ["*"] pour t’abonner à tous les événements.

Réponse de succès

{ "ok": true, "data": { "id": "wh_def456", "url": "https://your-app.com/webhooks/auris", "events": ["user.created", "user.updated", "login.failed"], "secret": "whsec_abc123xyz789...", "isActive": true, "createdAt": "2025-03-01T00:00:00Z" } }

Le champ secret est retourné uniquement à la création. Stocke-le immédiatement dans un endroit sécurisé — il ne pourra plus être récupéré. Pour générer un nouveau secret, utilise l’endpoint de rotation.


PATCH/api/webhooks/[id]Requires: manage:webhooks

Met à jour l’URL, les événements, la description ou le statut actif d’un webhook.

Corps de la requête

{ "events": ["user.created", "user.deleted"], "isActive": true }

DELETE/api/webhooks/[id]Requires: manage:webhooks

Supprime le webhook. Les livraisons en attente seront abandonnées.


Rotation du Secret

POST/api/webhooks/[id]/rotate-secretRequires: manage:webhooks

Génère un nouveau secret de signature pour le webhook. L’ancien secret est immédiatement invalidé. Le nouveau secret est retourné une seule fois.

Réponse de succès

{ "ok": true, "data": { "secret": "whsec_newxyz123..." } }

La rotation du secret invalide l’ancien secret immédiatement. Mets à jour la vérification de la signature côté serveur avant d’effectuer la rotation.


Test du Webhook

POST/api/webhooks/[id]/testRequires: manage:webhooks

Envoie un événement de test webhook.test à l’URL configurée. Utile pour vérifier la connectivité et la vérification de signature.

Réponse de succès

{ "ok": true, "data": { "delivered": true, "statusCode": 200, "responseTime": 145 } }

Logs de Livraison

GET/api/webhooks/[id]/deliveriesRequires: manage:webhooks

Liste l’historique des livraisons pour un webhook, avec statut, code HTTP de réponse et temps de réponse.

Réponse de succès

{ "ok": true, "data": { "data": [ { "id": "del_abc123", "event": "user.created", "status": "success", "httpStatus": 200, "responseTime": 145, "attemptCount": 1, "createdAt": "2025-03-01T10:00:00Z" }, { "id": "del_def456", "event": "login.failed", "status": "failed", "httpStatus": 500, "responseTime": 30000, "attemptCount": 3, "lastError": "Connection timeout", "createdAt": "2025-03-01T11:00:00Z" } ] } }

POST/api/webhooks/[id]/deliveries/[deliveryId]/retryRequires: manage:webhooks

Rejoue manuellement une livraison échouée. Le payload original est renvoyé immédiatement, sans attendre le prochain cycle de retry.


Types d’Événements

Événements d’Authentification

ÉvénementDéclenchement
login.successConnexion réussie (tous les méthodes)
login.failedTentative de connexion échouée
signup.completedNouvel utilisateur créé via le flux d’inscription
logout.completedDéconnexion de session
token.refreshedToken d’accès renouvelé via refresh token
magic_link.sentMagic link envoyé par email
magic_link.verifiedMagic link cliqué et vérifié

Événements de Gestion des Utilisateurs

ÉvénementDéclenchement
user.createdUtilisateur créé (via API, inscription ou import)
user.updatedDonnées utilisateur modifiées
user.deletedUtilisateur supprimé
user.enabledCompte utilisateur réactivé
user.disabledCompte utilisateur désactivé
user.email_verifiedAdresse email vérifiée
password.changedMot de passe changé par l’utilisateur
password.reset_requestedDemande de réinitialisation de mot de passe initiée

Événements de Rôles

ÉvénementDéclenchement
role.createdNouveau rôle créé
role.updatedPermissions du rôle modifiées
role.deletedRôle supprimé
role.assignedRôle assigné à un utilisateur
role.unassignedRôle retiré d’un utilisateur

Événements de Sécurité

ÉvénementDéclenchement
mfa.enabled2FA activée pour un compte utilisateur
mfa.disabled2FA désactivée pour un compte utilisateur
account.lockedCompte verrouillé après trop de tentatives échouées
account.unlockedCompte déverrouillé manuellement ou automatiquement
suspicious_login.detectedConnexion suspecte détectée (IP inhabituelle, géolocalisation, etc.)

Événements Organisations

ÉvénementDescription
organization.createdNouvelle organisation créée
organization.updatedDonnées de l’organisation mises à jour
organization.deletedOrganisation supprimée
organization.member_addedMembre ajouté à l’organisation
organization.member_removedMembre retiré de l’organisation
organization.member_role_changedRôle d’un membre modifié
organization.invitation_sentInvitation envoyée
organization.invitation_acceptedInvitation acceptée
organization.sso_activatedConnexion SSO activée

Événements Système

ÉvénementDescription
webhook.testÉvénement de test envoyé manuellement

Format du Payload

Chaque livraison de webhook envoie un payload JSON avec la structure suivante :

{ "event": "user.created", "timestamp": "2025-03-01T10:00:00.000Z", "tenant": "your-tenant-id", "data": { "user": { "id": "usr_abc123", "email": "[email protected]", "name": "Alice Martin", "createdAt": "2025-03-01T10:00:00Z" } } }

Le contenu du champ data varie selon le type d’événement.


Vérification des Signatures

Chaque requête webhook inclut deux headers :

  • X-Webhook-Signature : Signature HMAC-SHA256 encodée en hexadécimal
  • X-Webhook-Timestamp : Timestamp Unix de la livraison

Le payload signé est : {timestamp}.{rawBody}

Vérifie toujours la signature et le timestamp. Rejette les requêtes avec un timestamp supérieur à 5 minutes pour prévenir les attaques par replay.

const crypto = require('crypto'); function verifyWebhookSignature(rawBody, signature, timestamp, secret) { // Rejeter si le timestamp est trop ancien (protection replay) const now = Math.floor(Date.now() / 1000); if (Math.abs(now - parseInt(timestamp)) > 300) { return false; } const signedPayload = `${timestamp}.${rawBody}`; const expectedSignature = crypto .createHmac('sha256', secret) .update(signedPayload) .digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expectedSignature) ); } // Express.js app.post('/webhooks/auris', express.raw({ type: 'application/json' }), (req, res) => { const signature = req.headers['x-webhook-signature']; const timestamp = req.headers['x-webhook-timestamp']; const rawBody = req.body.toString(); if (!verifyWebhookSignature(rawBody, signature, timestamp, process.env.WEBHOOK_SECRET)) { return res.status(401).json({ error: 'Signature invalide' }); } const payload = JSON.parse(rawBody); console.log('Événement webhook reçu :', payload.event); res.status(200).json({ received: true }); });

Politique de Livraison

  • Timeout : 30 secondes par tentative
  • Retries : 3 tentatives automatiques en cas d’échec (timeout ou code HTTP non-2xx)
  • Délai de backoff : 1 minute, 5 minutes, 30 minutes
  • Désactivation automatique : Après 10 erreurs consécutives, le webhook est automatiquement désactivé. Réactive-le depuis la Console ou via l’endpoint PATCH.

Retourne toujours un code HTTP 2xx rapidement pour accuser réception du webhook, même si le traitement asynchrone prend plus de temps. Cela évite les timeouts et les retries inutiles.


Pages Associées