Webhooks

Un webhook es el canal para quienes quieren conectar una alerta con sus propias herramientas: un script, un tablero de estado, un sistema de guardias, un pequeño servicio que abre un ticket. Cuando un sitio web se cae, y cuando vuelve a funcionar, UptimeWire envía una petición HTTP a la dirección que configuraste.

Qué transporta un webhook

Las advertencias de certificado, dominio y DNS no se envían por webhook. Te llegan por correo electrónico y, si está conectado, por Telegram.

Configúralo

Configuras la dirección en tu cuenta de UptimeWire, en los ajustes de notificaciones de tu perfil. Solo el titular de la cuenta puede añadirla, cambiarla, probarla o eliminarla.

1. Introduce la dirección de tu receptor. Debe empezar por https://.
2. Pulsa «Save address». La primera vez que guardas se crea un secreto de firma.
3. Copia el secreto de firma en tu receptor. Empieza por whsec_.
4. Pulsa «Send test message». El resultado se muestra de inmediato.

La dirección es la misma para todos los sitios web de la cuenta. No puedes elegir una dirección distinta para un sitio web concreto.

Qué direcciones se aceptan

UptimeWire rechaza una dirección que:

• no use https:// o contenga un nombre de usuario o una contraseña;
• apunte a una red privada o interna, a la propia máquina o a un truco numérico, como una dirección IP decimal o hexadecimal;
• tenga más de 2048 caracteres.

La dirección se comprueba cuando la guardas y de nuevo antes de enviar cada mensaje.

El mensaje

La petición es un POST HTTP con un cuerpo JSON. Este ejemplo es ilustrativo: los valores son inventados.

{
  "id": "4182",
  "event": "incident.opened",
  "site": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "Shop",
    "url": "https://shop.example.com"
  },
  "incident": {
    "id": "00000000-0000-0000-0000-000000000001",
    "started_at": "2026-11-01T10:15:00Z",
    "ended_at": null,
    "duration_seconds": null,
    "cause": "HTTP 503"
  }
}

Para incident.closed el cuerpo tiene la misma forma, con ended_at y duration_seconds rellenados. Para test, site e incident son null. Las horas están en UTC.

El id identifica la entrega, no el incidente. La parte del incidente muestra su estado en el momento de enviar el mensaje, así que un incident.opened tardío ya puede llevar un ended_at. Ignora los campos que no conozcas, para que tu receptor siga funcionando si se añade un campo.

Cabeceras

Comprueba la firma

Cualquiera que conozca tu dirección puede enviarle una petición. La firma permite que tu receptor distinga un mensaje real de UptimeWire de uno falsificado.

La firma es un HMAC con SHA-256, escrito en hexadecimal. Se calcula con tu secreto de firma sobre el texto formado por la hora t, un punto y el cuerpo sin procesar.

Para comprobar un mensaje:

1. Lee el cuerpo sin procesar antes de analizarlo como JSON. Analizarlo y volver a escribirlo puede alterarlo.
2. Lee t y v1 de la cabecera X-UptimeWire-Signature.
3. Calcula el HMAC de t, un punto y el cuerpo sin procesar, con tu secreto de firma.
4. Compara tu resultado con v1 mediante una comparación de tiempo constante.
5. Rechaza el mensaje si t se aleja más de cinco minutos de tu propio reloj.

Si generas un secreto nuevo en tu cuenta, el anterior deja de funcionar de inmediato. No hay periodo de solapamiento.

Entrega y reintentos

Una entrega cuenta como correcta cuando tu receptor responde con un estado 2xx en menos de cinco segundos. Cualquier otra cosa es un fallo: otro estado, un tiempo de espera agotado, un problema de certificado o una conexión rechazada. UptimeWire no sigue las redirecciones, y una respuesta 3xx es un fallo.

Un mensaje fallido se intenta hasta cinco veces en total: de inmediato y después a los 1, 5, 30 y 120 minutos. Tras el último intento se marca como fallido. UptimeWire no te envía un correo al respecto, pero el panel muestra que una alerta no se entregó. No desactiva la dirección.

En casos raros el mismo mensaje puede llegar dos veces, y los mensajes pueden llegar desordenados. Guarda el id de cada mensaje que proceses y usa started_at para decidir qué estado es más reciente.

Qué puedes ver en tu cuenta

La tarjeta de webhook de tu cuenta tiene un registro de entregas con los últimos 20 mensajes. De cada uno muestra el sitio web, el tipo de mensaje, el estado (entregado, fallido, se reintentará, en espera o cancelado), el número de intentos y el resultado, como «Answered 200».

Límites

• Una dirección por cuenta, compartida por todos los sitios web. Solo el titular de la cuenta puede cambiarla.
• Solo caídas y recuperaciones.
• Incluido desde el plan Starter. Si una cuenta pasa a un plan sin webhooks, los mensajes en espera se cancelan y no se generan otros nuevos. La dirección y el secreto se conservan, y los mensajes se reanudan tras una mejora de plan.
• Los mensajes se envían al menos una vez, no exactamente una vez.
• UptimeWire no lee la respuesta que devuelve tu receptor.

Solución de problemas

• «This address is not allowed.» La dirección lleva a una red privada o interna. Usa una dirección pública.
• "The address must start with https://." No se acepta http:// a secas.
• «The address did not answer in 5 seconds.» Responde primero y haz el trabajo lento después, por ejemplo poniendo el mensaje en una cola.
• «Answered 3xx: redirects are not followed.» Configura la dirección final.
• Los mensajes llegan pero la firma no coincide. Comprueba que la calculas sobre el cuerpo sin procesar y que usas el secreto actual.
• «Too many test messages.» El botón de prueba está limitado a cinco por minuto.

Telegram, Discord, Slack y Microsoft Teams son canales aparte. Consulta la visión general de integraciones para ver qué transporta cada uno.