Enviar alertas a un webhook

Además del correo y de Slack, una alerta puede llamar a una dirección de tu propio sistema. Así abres un ticket automáticamente, guardas el evento en tu base de datos o disparas un flujo en Zapier, Make o n8n — ninguna de esas herramientas exige una integración dedicada: todas aceptan recibir un webhook.

Cómo configurarlo

1. Ve a Alertas y crea una alerta nueva (o edita una existente).

2. Completa el nombre, la condición y la encuesta, como en cualquier alerta.

3. En Métodos de Notificación, marca Webhook.

4. Indica la URL del endpoint que recibirá la llamada y guarda.

5. Después de guardar, aparece una clave de firma en el formulario. Cópiala y guárdala — con ella tu sistema confirma que la llamada vino de nosotros.

Requisitos de la URL

• Debe usar HTTPS. En HTTP el contenido y la firma viajarían abiertos.

• Debe ser accesible desde internet. Las direcciones internas (localhost, 192.168.x.x, 10.x.x.x) se rechazan por seguridad.

• No puede responder con una redirección — la entrega se hace a la dirección indicada, y solo a ella.

Qué enviamos

Un POST con Content-Type: application/json y un cuerpo con este formato:

{
  "event": "alert.triggered",
  "alert": {
    "id": "12",
    "name": "NPS crítico",
    "condition": "nps_below",
    "threshold": 30
  },
  "survey": {
    "id": "01jabc...",
    "title": "Postatención"
  },
  "context": {
    "current_nps": "12",
    "threshold": "30",
    "window": "últimos 30 días",
    "responses": "48"
  },
  "triggered_at": "2026-07-27T12:34:56-03:00"
}

Dos detalles importantes para quien va a programar:

• condition es un código estable, no un texto traducido. Los valores posibles son nps_below, nps_above, sentiment_negative, no_response, response_rate_below y new_feedback. Puedes usarlos en un switch sin miedo a que el idioma del panel cambie el comportamiento.

• survey llega como null cuando la alerta vale para todas las encuestas.

Verificando la firma

Cada llamada lleva la cabecera Signature, que es el HMAC-SHA256 del cuerpo usando tu clave de firma. Verifícala antes de actuar sobre el contenido — sin eso, cualquiera que descubra tu URL puede falsificar una alerta. En PHP:

$esperado = hash_hmac('sha256', $cuerpoCrudo, $tuClave);

if (! hash_equals($esperado, $request->header('Signature'))) {
    abort(403);
}

Reintentos

Si tu endpoint no responde con éxito, lo intentamos hasta 3 veces, esperando más entre cada intento. Cada llamada tiene un límite de 5 segundos — responde rápido (un 200 inmediato) y procesa después, en segundo plano.

Si los tres intentos fallan, la tarjeta de la alerta pasa a mostrar la última entrega falló con el motivo. Vale la pena revisar esa marca de vez en cuando: así te enteras de que la integración se detuvo.

Sobre privacidad

El payload no identifica a quien respondió. Cuando la encuesta es anónima, esa es una promesa hecha al encuestado — y vale también aquí: el comentario y la nota se envían, el nombre y el correo no.

Cambiar la URL o quitarla

Cambiar la dirección mantiene la misma clave de firma, así que no necesitas reconfigurar la verificación del otro lado. Desmarcar el método Webhook quita la URL y borra la clave — si vuelves a activarlo después, se generará una clave nueva.