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
/api/webhooksRequires: manage:webhooksListe 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"
}
]
}/api/webhooksRequires: manage:webhooksCré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.
/api/webhooks/[id]Requires: manage:webhooksMet à 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
}/api/webhooks/[id]Requires: manage:webhooksSupprime le webhook. Les livraisons en attente seront abandonnées.
Rotation du Secret
/api/webhooks/[id]/rotate-secretRequires: manage:webhooksGé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
/api/webhooks/[id]/testRequires: manage:webhooksEnvoie 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
/api/webhooks/[id]/deliveriesRequires: manage:webhooksListe 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"
}
]
}
}/api/webhooks/[id]/deliveries/[deliveryId]/retryRequires: manage:webhooksRejoue 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énement | Déclenchement |
|---|---|
login.success | Connexion réussie (tous les méthodes) |
login.failed | Tentative de connexion échouée |
signup.completed | Nouvel utilisateur créé via le flux d’inscription |
logout.completed | Déconnexion de session |
token.refreshed | Token d’accès renouvelé via refresh token |
magic_link.sent | Magic link envoyé par email |
magic_link.verified | Magic link cliqué et vérifié |
Événements de Gestion des Utilisateurs
| Événement | Déclenchement |
|---|---|
user.created | Utilisateur créé (via API, inscription ou import) |
user.updated | Données utilisateur modifiées |
user.deleted | Utilisateur supprimé |
user.enabled | Compte utilisateur réactivé |
user.disabled | Compte utilisateur désactivé |
user.email_verified | Adresse email vérifiée |
password.changed | Mot de passe changé par l’utilisateur |
password.reset_requested | Demande de réinitialisation de mot de passe initiée |
Événements de Rôles
| Événement | Déclenchement |
|---|---|
role.created | Nouveau rôle créé |
role.updated | Permissions du rôle modifiées |
role.deleted | Rôle supprimé |
role.assigned | Rôle assigné à un utilisateur |
role.unassigned | Rôle retiré d’un utilisateur |
Événements de Sécurité
| Événement | Déclenchement |
|---|---|
mfa.enabled | 2FA activée pour un compte utilisateur |
mfa.disabled | 2FA désactivée pour un compte utilisateur |
account.locked | Compte verrouillé après trop de tentatives échouées |
account.unlocked | Compte déverrouillé manuellement ou automatiquement |
suspicious_login.detected | Connexion suspecte détectée (IP inhabituelle, géolocalisation, etc.) |
Événements Organisations
| Événement | Description |
|---|---|
organization.created | Nouvelle organisation créée |
organization.updated | Données de l’organisation mises à jour |
organization.deleted | Organisation supprimée |
organization.member_added | Membre ajouté à l’organisation |
organization.member_removed | Membre retiré de l’organisation |
organization.member_role_changed | Rôle d’un membre modifié |
organization.invitation_sent | Invitation envoyée |
organization.invitation_accepted | Invitation acceptée |
organization.sso_activated | Connexion SSO activée |
Événements Système
| Événement | Description |
|---|---|
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écimalX-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.
Node.js
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
- Guide Webhooks — Configurer et consommer les webhooks
- Console Webhooks — Gérer les webhooks depuis l’interface
- API Actions — Déclencher des webhooks via le moteur d’actions
- SDK JavaScript — Utilitaires de vérification de signature inclus