Guía de integración de Webhook

Si configuras un Webhook, Miharu envía sus resultados de monitoreo (alertas del sistema) a la URL que indiques mediante un POST HTTP con cuerpo JSON. Así puedes conectarlo con Zapier, Make, n8n, tu propio servidor y más, y procesar las notificaciones como quieras.

Esta función está pensada para desarrolladores y usuarios avanzados. Hace falta un endpoint receptor de tu lado.

1. Configuración

1. 1En la app, abre “Notificaciones externas” → “Webhook”.
2. 2Escribe la URL del Webhook de destino (debe empezar por https://).
3. 3Si lo necesitas, define el filtro de notificaciones (por ejemplo, solo un grupo de monitoreo concreto).
4. 4Al guardar se envía una notificación de prueba que confirma la configuración.

2. Especificación HTTP

No se envía ningún encabezado de firma (HMAC u otro). La propia URL del Webhook es el secreto (consulta Seguridad más abajo).

3. Payload (campos comunes)

4. Tipos de evento y detail

El diff de page_changed

diff es un arreglo con los cambios. Cada elemento es uno de estos:

• { "op": "added", "text": "..." }… una línea agregada
• { "op": "removed", "text": "..." }… una línea eliminada
• { "op": "replaced", "before": "...", "after": "..." }… una línea sustituida

Si truncated es true, la diferencia era grande y se omitió una parte.

5. Ejemplos

{
  "source": "miharu",
  "version": "1",
  "id": "5c2e1b7a-9f3d-5a6b-8c4e-1d2f3a4b5c6d",
  "timestamp": "2026-05-22T01:23:45Z",
  "language": "es",
  "event": "page_changed",
  "monitor": { "id": "abc123", "name": "Página de producto", "url": "https://example.com/item" },
  "message": { "body": "La página se ha actualizado.", "label": "Actualización" },
  "detail": {
    "diff": [
      { "op": "replaced", "before": "Agotado", "after": "Disponible" },
      { "op": "added", "text": "Repuesto hoy" }
    ],
    "truncated": false
  }
}

{
  "source": "miharu", "version": "1", "id": "…",
  "timestamp": "2026-05-22T01:23:45Z", "language": "es",
  "event": "keyword_hit",
  "monitor": { "id": "abc123", "name": "Página de disponibilidad", "url": "https://example.com/stock" },
  "message": { "body": "Se ha detectado una palabra clave.", "label": "Palabra clave" },
  "detail": { "hits": [ { "keywords": ["repuesto"], "excerpts": ["…repuesto hoy…"] } ] }
}

{
  "…": "…",
  "event": "new_link",
  "message": { "body": "Se ha detectado un enlace nuevo.", "label": "Enlace nuevo" },
  "detail": { "links": [ { "text": "Anuncio de un producto nuevo", "url": "https://example.com/news/123" } ] }
}

{
  "…": "…",
  "event": "price_changed",
  "message": { "body": "“Precio” ha cambiado.\n\n1980 → 1480", "label": "Precio/Valor" },
  "detail": { "target_name": "Precio", "before": "1980", "after": "1480" }
}

6. Idempotencia (descarte de duplicados)

Un mismo evento llega siempre con el mismo id, incluso en los reintentos (ese mismo valor está también en el encabezado X-Miharu-Notification-Id). Usa id de tu lado para no procesar dos veces la misma notificación.

7. Seguridad

• HTTPS obligatorio (solo se pueden registrar URL con https://).
• No se envía ningún encabezado de firma, así que trata la propia URL del Webhook como un secreto (si se filtra, un tercero podría enviar notificaciones falsas).
• Si lo necesitas, incluye un token aleatorio en la URL (por ejemplo https://example.com/hook/<aleatorio>) y verifícalo de tu lado.
• Como indicio aproximado del origen puedes usar User-Agent: Miharu-Webhook/1.0 y los encabezados X-Miharu-* (solo como apoyo).

8. Integraciones

Genera una URL de recepción en tu servicio y regístrala en Miharu como URL del Webhook.

• Zapier: la URL de “Webhooks by Zapier” → “Catch Hook”
• Make: la URL de un “Custom webhook”
• n8n: la URL de un nodo “Webhook”
• Tu propio servidor: un endpoint que acepte el cuerpo JSON y devuelva 2xx

9. Limitaciones

• Por Webhook llegan las alertas del sistema (las detecciones) y las notificaciones del sistema.
• Las diferencias o los textos largos pueden recortarse (por ejemplo truncated: true).
• Con el filtro de notificaciones puedes limitar el envío a un grupo de monitoreo concreto.

10. Resolución de problemas

• ¿La URL empieza por https://?
• ¿Tu endpoint devuelve 2xx? (Las redirecciones y los errores cuentan como fallo.)
• ¿Se detuvo el envío tras varias respuestas seguidas distintas de 2xx? Revisa el estado en la app y vuelve a configurarlo para reanudarlo.
• ¿El procesamiento tarda más de 10 segundos (tiempo de espera)? Devuelve 2xx de inmediato y procesa de forma asíncrona.

Si tienes alguna observación o sugerencia, escríbenos desde “Comentarios y sugerencias” en la app.