Webhooks

Que son los Webhooks?

Los webhooks son solicitudes HTTP POST automatizadas que dat2ai envia a tu servidor cuando ocurren eventos especificos en tu sitio. En lugar de consultar la API para nuevos eventos, tu servidor los recibe en tiempo real.

Por ejemplo, puedes recibir una notificacion instantanea en Slack cuando un agente de IA envia un formulario de contacto, o registrar la interaccion en tu sistema CRM automaticamente.

Configuracion

Crea un endpoint de webhook desde el dashboard de dat2ai para empezar a recibir notificaciones de eventos.

Formato del Payload

Cada entrega de webhook envia un payload JSON que contiene un array de eventos y metadatos:

{
  "events": [
    {
      "event_id": "evt_abc123",
      "site_id": "site_xyz",
      "tool_name": "contact-form",
      "event_type": "invocation",
      "agent_type": "browser_agent",
      "consent_given": true,
      "timestamp": "2026-02-16T12:00:00Z"
    }
  ],
  "siteId": "site_xyz",
  "timestamp": "2026-02-16T12:00:00Z"
}

El array de eventos puede contener uno o mas eventos. Los eventos se agrupan por eficiencia — tu endpoint puede recibir multiples eventos en una sola solicitud.

Verificacion de Firma

Cada solicitud de webhook incluye una cabecera X-Webhook-Signature que contiene una firma HMAC-SHA256. Siempre verifica esta firma para asegurar que la solicitud proviene de dat2ai y no fue manipulada.

Aqui hay un ejemplo en Node.js para verificar la firma del webhook:

const crypto = require('crypto');

function verifyWebhookSignature(req, webhookSecret) {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);

  const expected = crypto
    .createHmac('sha256', webhookSecret)
    .update(payload)
    .digest('hex');

  const valid = crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );

  return valid;
}

// Express.js example
app.post('/webhook', (req, res) => {
  if (!verifyWebhookSignature(req, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { events } = req.body;
  for (const event of events) {
    console.log('Received:', event.event_type, event.tool_name);
  }

  res.status(200).json({ received: true });
});

Siempre usa crypto.timingSafeEqual para comparar firmas y prevenir ataques de timing. Nunca uses igualdad simple de strings (===).

Tipos de Eventos

Los siguientes tipos de eventos pueden activar entregas de webhook:

Entrega

Como dat2ai entrega las notificaciones de webhook a tu endpoint:

Casos de Uso