Configurer les Webhooks

Les webhooks permettent à ton application de recevoir des notifications HTTP en temps réel quand des événements se produisent dans Auris, comme l’inscription d’un utilisateur, un login échoué, l’assignation d’un rôle ou la création d’une organisation. Au lieu de faire du polling sur les APIs Auris pour détecter les changements, Auris envoie les payloads d’événements à ton endpoint au moment où quelque chose se passe.

Cas d’usage courants

• Synchroniser les données utilisateur dans ta base de données quand un utilisateur est créé ou mis à jour
• Démarrer des workflows d’onboarding quand un nouvel utilisateur s’inscrit
• Révoquer l’accès dans ton système quand un utilisateur est désactivé ou supprimé
• Audit logging en transmettant des événements à ton SIEM
• Notifications Slack/Teams quand une activité de connexion suspecte est détectée

Étape 1 : Crée un Endpoint Webhook dans Ton Application

Ton endpoint webhook est un handler HTTP POST standard qui reçoit des payloads JSON depuis Auris :

import express from 'express'
import crypto from 'crypto'
 
const app = express()
 
// IMPORTANT : Utilise le body brut pour la vérification de signature
app.post(
  '/webhooks/auris',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-webhook-signature'] as string
    const timestamp = req.headers['x-webhook-timestamp'] as string
    const secret = process.env.AURIS_WEBHOOK_SECRET!
 
    if (!verifyWebhookSignature(req.body, signature, timestamp, secret)) {
      console.error('Vérification de signature webhook échouée')
      return res.status(401).json({ error: 'Signature invalide' })
    }
 
    const event = JSON.parse(req.body.toString())
 
    // Répondre 200 immédiatement — traiter de façon asynchrone
    res.status(200).json({ received: true })
 
    handleWebhookEvent(event).catch((err) =>
      console.error('Erreur handler webhook:', err)
    )
  }
)
 
function verifyWebhookSignature(
  body: Buffer,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  // Protection replay — rejeter si le timestamp est plus vieux de 5 minutes
  const eventTime = parseInt(timestamp, 10)
  const now = Math.floor(Date.now() / 1000)
  if (Math.abs(now - eventTime) > 300) return false
 
  const payload = `${timestamp}.${body.toString()}`
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex')
 
  try {
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  } catch {
    return false
  }
}

Étape 2 : Enregistre le Webhook dans la Console Auris

1. Ouvre la Console Auris et navigue dans Paramètres → Webhooks
2. Clique sur Créer un Webhook
3. Saisis l’URL de ton endpoint (ex. https://api.votreapp.com/webhooks/auris)
4. Sélectionne les événements que tu souhaites recevoir (ou choisis “Tous les événements”)
5. Clique Créer

Auris génère un secret de signature avec le préfixe whsec_. Copie cette valeur immédiatement et conserve-la en sécurité dans les variables d’environnement. Le secret complet est affiché une seule fois.

Étape 3 : Vérifie les Signatures Webhook

Chaque livraison webhook depuis Auris inclut deux headers pour la vérification :

La signature est calculée comme :

HMAC-SHA256(whsec_secret, "${timestamp}.${rawBody}")

Catalogue des Événements

Événements Utilisateur

Événements de Connexion

Événements Rôles et Permissions

Événements Organisation

Exemple de Payload

{
  "id": "evt_abc123def456",
  "type": "user.created",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "id": "usr_xyz789",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "emailVerified": false,
    "roles": [],
    "createdAt": "2026-01-15T10:30:00Z"
  }
}

Gestion des Échecs et des Retries

Si ton endpoint retourne un code de statut non-2xx ou ne répond pas dans les 30 secondes, Auris considère la livraison comme échouée et réessaie avec un backoff exponentiel :

Après 5 retries échoués (6 tentatives totales), la livraison est marquée comme définitivement échouée.

Test des Webhooks

Bouton Test dans la Console

Dans la Console Auris, chaque webhook a un bouton Test qui envoie un événement synthétique à ton endpoint.

Développement Local avec ngrok

# Démarre ton serveur webhook local
node server.js
 
# Dans un autre terminal, démarre ngrok
ngrok http 3000

ngrok fournit une URL publique comme https://a1b2c3d4.ngrok-free.app. Utilise cette URL lors de l’enregistrement du webhook dans la Console.

Bonnes Pratiques

Réponds 200 immédiatement. Ton endpoint devrait retourner HTTP 200 le plus rapidement possible, puis traiter l’événement de façon asynchrone.

Implémente l’idempotence. Chaque événement inclut un champ id unique. Conserve les IDs des événements traités et ignore les doublons.

async function handleWebhookEvent(event: { id: string; type: string; data: unknown }) {
  const exists = await db.processedWebhookEvent.findUnique({
    where: { eventId: event.id },
  })
  if (exists) return // Événement déjà traité
 
  await processEvent(event)
 
  await db.processedWebhookEvent.create({
    data: { eventId: event.id, processedAt: new Date() },
  })
}

Utilise des endpoints HTTPS. Auris envoie les payloads webhook uniquement sur HTTPS.

Fais tourner les secrets périodiquement. Utilise la Console ou l’API pour faire tourner le secret de signature du webhook.

Guides Associés

• Log Streaming — Transmets les logs d’audit à des services externes comme Datadog et Splunk
• Actions Engine — Exécute de la logique personnalisée pendant les flux d’authentification
• Protection contre les Attaques — Pipeline de sécurité et détection de connexions suspectes