Webhooks

Recibe notificaciones en tiempo real cuando ocurren eventos en tu aplicacion.

Configuracion

1. Ve al Dashboard de Auris → Webhooks
2. Click en "Crear Webhook"
3. Ingresa la URL de tu endpoint
4. Selecciona los eventos que deseas recibir
5. Copia el Signing Secret generado

Eventos disponibles

Usuarios

• user.created - Nuevo usuario registrado
• user.updated - Datos de usuario actualizados
• user.deleted - Usuario eliminado
• user.signed_in - Inicio de sesion
• user.signed_out - Cierre de sesion

Sesiones

• session.created - Nueva sesion iniciada
• session.revoked - Sesion revocada
• session.expired - Sesion expirada

Organizaciones

• organization.created - Nueva organizacion
• organization.updated - Organizacion actualizada
• organization.deleted - Organizacion eliminada
• organization.member_added - Nuevo miembro
• organization.member_removed - Miembro removido
• organization.member_updated - Rol de miembro actualizado
• organization.invitation_created - Invitacion creada
• organization.invitation_accepted - Invitacion aceptada

Formato del payload

{
  "id": "evt_xxxxx",
  "type": "user.created",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "data": {
    "id": "user_xxxxx",
    "email": "nuevo@email.com",
    "firstName": "Juan",
    "lastName": "Perez",
    "emailVerified": false,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Verificar firma

Siempre verifica la firma del webhook para asegurar que proviene de Auris. La firma se envia en el header auris-signature.

Node.js

import { verifyWebhook } from '@auris/node';

// Express con raw body
app.post(
  '/api/webhooks/auris',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['auris-signature'];
    const webhookSecret = process.env.AURIS_WEBHOOK_SECRET;

    try {
      const event = verifyWebhook(req.body, signature, webhookSecret);

      // Procesar evento
      handleEvent(event);

      res.json({ received: true });
    } catch (error) {
      console.error('Webhook invalido:', error.message);
      res.status(400).json({ error: 'Firma invalida' });
    }
  }
);

Next.js App Router

// app/api/webhooks/auris/route.ts
import { verifyWebhook } from '@auris/node';
import { headers } from 'next/headers';
import { NextResponse } from 'next/server';

export async function POST(request: Request) {
  const body = await request.text();
  const headersList = await headers();
  const signature = headersList.get('auris-signature');

  if (!signature) {
    return NextResponse.json(
      { error: 'Missing signature' },
      { status: 400 }
    );
  }

  try {
    const event = verifyWebhook(
      body,
      signature,
      process.env.AURIS_WEBHOOK_SECRET!
    );

    await handleEvent(event);

    return NextResponse.json({ received: true });
  } catch (error) {
    return NextResponse.json(
      { error: 'Invalid signature' },
      { status: 400 }
    );
  }
}

async function handleEvent(event: WebhookEvent) {
  switch (event.type) {
    case 'user.created':
      await onUserCreated(event.data);
      break;
    case 'user.deleted':
      await onUserDeleted(event.data);
      break;
    // ...
  }
}

Ejemplos de manejo de eventos

Sincronizar con base de datos

async function handleEvent(event: WebhookEvent) {
  switch (event.type) {
    case 'user.created': {
      // Crear registro en tu base de datos
      await db.users.create({
        data: {
          aurisId: event.data.id,
          email: event.data.email,
          name: `${event.data.firstName} ${event.data.lastName}`,
        },
      });
      break;
    }

    case 'user.updated': {
      // Actualizar registro
      await db.users.update({
        where: { aurisId: event.data.id },
        data: {
          email: event.data.email,
          name: `${event.data.firstName} ${event.data.lastName}`,
        },
      });
      break;
    }

    case 'user.deleted': {
      // Eliminar o marcar como eliminado
      await db.users.update({
        where: { aurisId: event.data.id },
        data: { deletedAt: new Date() },
      });
      break;
    }
  }
}

Enviar email de bienvenida

case 'user.created': {
  await sendEmail({
    to: event.data.email,
    subject: 'Bienvenido a nuestra plataforma',
    template: 'welcome',
    data: {
      name: event.data.firstName,
    },
  });
  break;
}

Notificar en Slack

case 'user.signed_in': {
  if (event.data.newDevice) {
    await slack.send({
      channel: '#security',
      text: `Nuevo dispositivo detectado para ${event.data.email}`,
    });
  }
  break;
}

Reintentos

Si tu endpoint falla (responde con status 4xx o 5xx), Auris reintentara el webhook automaticamente:

• 1er reintento: 1 minuto despues
• 2do reintento: 5 minutos despues
• 3er reintento: 30 minutos despues
• 4to reintento: 2 horas despues
• 5to reintento: 24 horas despues

Testing local

Usa una herramienta como ngrok para probar webhooks en desarrollo:

# Instalar ngrok
npm install -g ngrok

# Exponer tu servidor local
ngrok http 3000

# Copiar la URL generada (ej: https://abc123.ngrok.io)
# Configurar en Dashboard: https://abc123.ngrok.io/api/webhooks/auris

Logs y debugging

En el Dashboard de Auris puedes ver el historial de webhooks enviados, incluyendo:

• Payload enviado
• Respuesta de tu servidor
• Tiempo de respuesta
• Intentos de reenvio