Webhook de monitorización web

Por qué usar un webhook

El email y Slack son destinos fijos. Un webhook es una sola integración que llega a cualquier cosa con un endpoint HTTP: en cuanto falla una comprobación puedes avisar a quien esté de guardia, abrir un ticket con el error ya rellenado o registrar el fallo para el informe de un cliente, sin que nadie copie datos de un email.

Cada petición lleva los mismos campos estructurados —el sitio, la comprobación, su gravedad, el error, qué lanzó la ejecución y un enlace a ella—, así que el receptor puede decidir en lugar de analizar texto: avisar a alguien solo cuando falla el checkout de forma crítica y abrir un ticket para todo lo demás.

Qué necesitas

Las alertas por webhook están en los planes Pro, Business y Agency.

Necesitas una dirección https en internet que responda con cualquier estado 2xx en menos de 10 segundos. Puede ser una pequeña función tuya o el disparador de webhook de una herramienta de automatización: el Catch Hook de Zapier, el Custom webhook de Make o el nodo Webhook de n8n aceptan el JSON de Relvato tal cual.

Paso 1 — Añade la URL del webhook

En Relvato, abre el menú de la cuenta arriba a la derecha y elige Alert settings. En la sección Webhook, pega tu dirección y pulsa Save preferences.

Relvato solo acepta direcciones https que resuelvan a internet y nunca sigue redirecciones, así que usa la dirección final. Al guardar se crea un secreto de firma para el webhook. Como en un webhook de Slack, la dirección puede contener un token, así que después de guardar la página solo muestra el nombre del host.

app.relvato.com/alerts

Paso 2 — Copia el secreto de firma

Junto a Signing secret, pulsa Show y luego Copy, y guárdalo donde tu receptor pueda leerlo, por ejemplo en una variable de entorno llamada RELVATO_WEBHOOK_SECRET. Empieza por whsec_.

Rotate crea un secreto nuevo al instante; el anterior deja de verificar, así que actualiza tu receptor a la vez.

Paso 3 — Envía una prueba

Pulsa Send test webhook al final de la página. Relvato envía un evento de tipo test, firmado como uno real, y te dice si tu endpoint respondió, por ejemplo «Test event delivered (HTTP 200)». Si no, el mensaje explica por qué: sin respuesta en 10 segundos, una redirección o el estado que devolvió tu endpoint.

Paso 4 — Elige qué va al webhook

En What goes where, la columna Webhook tiene un interruptor por tipo de comprobación: User flows, Security, Design, Performance, SEO / AEO, Domain lifecycle y Other. Desactiva los que no quieras en tus herramientas; el email y Slack tienen sus propios interruptores.

El resto de Alert settings también se aplica: Sites decide qué sitios avisan y Alert me on fija la gravedad mínima que se envía. El webhook es instantáneo: deja marcado As it happens; los resúmenes diarios y semanales son solo por email.

app.relvato.com/alerts

Qué envía Relvato

Cada alerta es un POST con Content-Type: application/json y tres cabeceras: Relvato-Event (el tipo de evento), Relvato-Delivery (un id único que se mantiene si se reintenta un envío, para ignorar duplicados) y Relvato-Signature.

Hay cuatro tipos de evento: check.failed cuando una comprobación empieza a fallar (o falla al lanzarla tú), check.passed cuando está activado «Tell me about every run», quarantine.change para los mensajes de inicio, cambios y resumen del modo cuarentena, y test desde el botón de arriba. Todos tienen la misma forma, con las partes que no aplican a null.

app.relvato.com/alerts

Verifica la firma

Relvato-Signature tiene la forma t=1790000000,v1=…: t es la hora Unix de la petición y v1 es un HMAC-SHA256, con tu secreto de firma, de la marca de tiempo, un punto y el cuerpo bruto de la petición. Recalcúlalo sobre el cuerpo tal como llegó (no el JSON vuelto a serializar), compáralo en tiempo constante y rechaza marcas de más de cinco minutos, para que una petición capturada no se pueda reenviar después.

El disparador de webhook de una herramienta de automatización no suele poder comprobar firmas. Está bien para usos de poco riesgo como un registro; cuando un webhook puede abrir incidencias o cambiar cosas, pon delante una pequeña función que verifique la firma.

import crypto from "node:crypto";
import express from "express";

const app = express();

// Keep the RAW body: the signature is over the exact bytes Relvato sent.
app.post("/relvato-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("Relvato-Signature") ?? "";      // "t=1790000000,v1=5f2c…"
  const t = Number(/t=(\d+)/.exec(header)?.[1]);
  const v1 = /v1=([0-9a-f]{64})/.exec(header)?.[1] ?? "";
  const expected = crypto
    .createHmac("sha256", process.env.RELVATO_WEBHOOK_SECRET)
    .update(`${t}.${req.body}`)
    .digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - t) < 300;    // refuse replays older than 5 minutes
  if (!fresh || v1.length !== 64 ||
      !crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString());
  res.sendStatus(200);                                     // answer fast, then do the slow work
  handle(event);                                           // switch on event.type
});

Ejemplos prácticos

Avisar a quien está de guardia. Envía los eventos check.failed a n8n o Make, quédate con los de gravedad critical —un checkout o un paso de pago roto— y crea una incidencia en PagerDuty u Opsgenie con el sitio, el error y el enlace a la ejecución.

Abrir un ticket automáticamente. Un Catch Hook de Zapier convierte cada fallo en una incidencia de Jira, Linear o GitHub: el nombre de la comprobación como título, el error y los cambios en la descripción, y el enlace a la ejecución para reproducirlo.

Publicar en Microsoft Teams, Discord o Google Chat. Esperan su propio formato de mensaje, así que pasa el webhook por Make, n8n o Zapier y asigna los campos de Relvato al mensaje.

Llevar un registro de fallos para informes a clientes. Añade una fila por evento a Google Sheets o a tu almacén de datos y luego informa de cuántas veces falló cada sitio, qué comprobaciones y cuánto tardaron los arreglos.

Agencias: dirigir por sitio. Cada evento lleva site.id y site.name, así que un solo webhook puede enviar las alertas de cada cliente a su canal o proyecto.

Reaccionar a un despliegue fallido. Cuando llega check.failed con un despliegue como disparador, tu pipeline puede abrir un pull request de reversión para que alguien lo apruebe; mantén a una persona en el proceso antes de cambiar nada en el sitio en producción.

Reintentos, duplicados y pausa

Si tu endpoint no responde, tarda más de 10 segundos o devuelve un estado 5xx o 429, Relvato lo reintenta a los 2 segundos y de nuevo a los 8. Los demás estados 4xx y las redirecciones no se reintentan, porque la respuesta no cambiaría. Cada envío queda registrado en la ejecución, y uno fallido muestra el motivo en Alert settings.

Un reintento lleva el mismo id en Relvato-Delivery. Guarda los ids que ya procesaste y omite los repetidos.

Tras 20 envíos fallidos seguidos, Relvato pausa el webhook y te avisa: la campana de notificaciones muestra «Webhook alerts paused» con el último error, y Alert settings lo muestra con un botón Resume. Arregla el receptor y pulsa Resume.

Cambiar o quitar el webhook

Para enviarlo a otro sitio, pega la dirección nueva y guarda; el secreto de firma no cambia. Para dejar de enviar sin perder la configuración, desmarca Send alerts to the webhook. Para quitarlo del todo, marca Remove on save y pulsa Save preferences: Relvato borra la dirección y el secreto de firma; la política de privacidad tiene los detalles.