Configurare i Webhook

I webhook consentono alla tua applicazione di ricevere notifiche HTTP in tempo reale quando si verificano eventi in Auris, come la registrazione di un utente, un login fallito, l’assegnazione di un ruolo o la creazione di un’organizzazione. Invece di fare polling alle API Auris per rilevare le modifiche, Auris invia i payload degli eventi al tuo endpoint nel momento in cui accade qualcosa.

Casi d’uso comuni

• Sincronizza dati utente nel tuo database quando un utente viene creato o aggiornato
• Avvia workflow di onboarding quando si registra un nuovo utente
• Revoca l’accesso nel tuo sistema quando un utente viene disabilitato o eliminato
• Audit logging trasmettendo eventi al tuo SIEM
• Notifiche Slack/Teams quando viene rilevata attività di login sospetta

Passo 1: Crea un Endpoint Webhook nella Tua Applicazione

Il tuo endpoint webhook è un handler HTTP POST standard che riceve payload JSON da Auris:

import express from 'express'
import crypto from 'crypto'
 
const app = express()
 
// IMPORTANTE: Usa il body grezzo per la verifica della firma
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('Verifica firma webhook fallita')
      return res.status(401).json({ error: 'Firma non valida' })
    }
 
    const event = JSON.parse(req.body.toString())
 
    // Rispondi 200 immediatamente — elabora in modo asincrono
    res.status(200).json({ received: true })
 
    handleWebhookEvent(event).catch((err) =>
      console.error('Errore handler webhook:', err)
    )
  }
)
 
function verifyWebhookSignature(
  body: Buffer,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  // Protezione replay — rifiuta se il timestamp è più vecchio di 5 minuti
  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
  }
}

Passo 2: Registra il Webhook nella Console Auris

1. Apri la Console Auris e naviga in Impostazioni → Webhook
2. Clicca su Crea Webhook
3. Inserisci l’URL del tuo endpoint (es. https://api.tuaapp.com/webhooks/auris)
4. Seleziona gli eventi che vuoi ricevere (o scegli “Tutti gli eventi”)
5. Clicca Crea

Auris genera un segreto di firma con prefisso whsec_. Copia questo valore immediatamente e conservalo in modo sicuro nelle variabili d’ambiente. Il segreto completo viene mostrato una sola volta.

Passo 3: Verifica le Firme Webhook

Ogni consegna webhook da Auris include due header per la verifica:

La firma viene calcolata come:

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

Catalogo degli Eventi

Eventi Utente

Eventi di Login

Eventi Ruoli e Permessi

Eventi Organizzazione

Payload di Esempio

{
  "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"
  }
}

Gestione dei Fallimenti e dei Retry

Se il tuo endpoint restituisce un codice di stato non-2xx o non risponde entro 30 secondi, Auris considera la consegna fallita e riprova con backoff esponenziale:

Dopo 5 retry falliti (6 tentativi totali), la consegna viene contrassegnata come definitivamente fallita.

Test dei Webhook

Pulsante Test nella Console

Nella Console Auris, ogni webhook ha un pulsante Test che invia un evento sintetico al tuo endpoint.

Sviluppo Locale con ngrok

# Avvia il tuo server webhook locale
node server.js
 
# In un altro terminale, avvia ngrok
ngrok http 3000

ngrok fornisce un URL pubblico come https://a1b2c3d4.ngrok-free.app. Usa questo URL quando registri il webhook nella Console.

Best Practice

Rispondi 200 immediatamente. Il tuo endpoint dovrebbe restituire HTTP 200 il più velocemente possibile, poi elaborare l’evento in modo asincrono.

Implementa l’idempotenza. Ogni evento include un campo id univoco. Conserva gli ID degli eventi elaborati e salta i duplicati.

async function handleWebhookEvent(event: { id: string; type: string; data: unknown }) {
  const exists = await db.processedWebhookEvent.findUnique({
    where: { eventId: event.id },
  })
  if (exists) return // Evento già elaborato
 
  await processEvent(event)
 
  await db.processedWebhookEvent.create({
    data: { eventId: event.id, processedAt: new Date() },
  })
}

Usa endpoint HTTPS. Auris invia payload webhook solo su HTTPS.

Ruota i segreti periodicamente. Usa la Console o l’API per ruotare il segreto di firma del webhook.

Guide Correlate

• Log Streaming — Trasmetti i log di audit a servizi esterni come Datadog e Splunk
• Actions Engine — Esegui logica personalizzata durante i flussi di autenticazione
• Attack Protection — Pipeline di sicurezza e rilevamento login sospetti