Guia de integração de Webhook

Ao configurar um Webhook, o Miharu envia os resultados do monitoramento (alertas do sistema) para a URL que você indicar, como um POST HTTP com corpo JSON. Assim dá para integrar com Zapier, Make, n8n, seu próprio servidor e mais, e tratar as notificações como preferir.

Este recurso é voltado a desenvolvedores e usuários avançados. É preciso um endpoint receptor do seu lado.

1. Configuração

1. 1No app, abra “Notificações externas” → “Webhook”.
2. 2Digite a URL do Webhook de destino (precisa começar com https://).
3. 3Se quiser, defina o filtro de notificações (por exemplo, apenas um grupo de monitoramento).
4. 4Ao salvar, é enviada uma notificação de teste confirmando a configuração.

2. Especificação HTTP

Nenhum cabeçalho de assinatura (HMAC ou outro) é enviado. A própria URL do Webhook é o segredo (veja Segurança abaixo).

3. Payload (campos comuns)

4. Tipos de evento e detail

O diff de page_changed

diff é um array com as mudanças. Cada elemento é um destes:

• { "op": "added", "text": "..." }… uma linha adicionada
• { "op": "removed", "text": "..." }… uma linha removida
• { "op": "replaced", "before": "...", "after": "..." }… uma linha substituída

Se truncated for true, a diferença era grande e parte dela foi omitida.

5. Exemplos

{
  "source": "miharu",
  "version": "1",
  "id": "5c2e1b7a-9f3d-5a6b-8c4e-1d2f3a4b5c6d",
  "timestamp": "2026-05-22T01:23:45Z",
  "language": "pt",
  "event": "page_changed",
  "monitor": { "id": "abc123", "name": "Página do produto", "url": "https://example.com/item" },
  "message": { "body": "A página foi atualizada.", "label": "Atualização" },
  "detail": {
    "diff": [
      { "op": "replaced", "before": "Sem estoque", "after": "Em estoque" },
      { "op": "added", "text": "Reposto hoje" }
    ],
    "truncated": false
  }
}

{
  "source": "miharu", "version": "1", "id": "…",
  "timestamp": "2026-05-22T01:23:45Z", "language": "pt",
  "event": "keyword_hit",
  "monitor": { "id": "abc123", "name": "Página de disponibilidade", "url": "https://example.com/stock" },
  "message": { "body": "Uma palavra-chave foi detectada.", "label": "Palavra-chave" },
  "detail": { "hits": [ { "keywords": ["reposto"], "excerpts": ["…reposto hoje…"] } ] }
}

{
  "…": "…",
  "event": "new_link",
  "message": { "body": "Um link novo foi detectado.", "label": "Link novo" },
  "detail": { "links": [ { "text": "Anúncio de um produto novo", "url": "https://example.com/news/123" } ] }
}

{
  "…": "…",
  "event": "price_changed",
  "message": { "body": "“Preço” mudou.\n\n1980 → 1480", "label": "Preço/Valor" },
  "detail": { "target_name": "Preço", "before": "1980", "after": "1480" }
}

6. Idempotência (descarte de duplicatas)

O mesmo evento sempre chega com o mesmo id, inclusive nas retentativas (esse mesmo valor também vai no cabeçalho X-Miharu-Notification-Id). Use o id do seu lado para não processar a mesma notificação duas vezes.

7. Segurança

• HTTPS obrigatório (só é possível cadastrar URLs com https://).
• Nenhum cabeçalho de assinatura é enviado, então trate a própria URL do Webhook como um segredo (se vazar, um terceiro pode enviar notificações falsas).
• Se precisar, inclua um token aleatório na URL (por exemplo https://example.com/hook/<aleatorio>) e valide-o do seu lado.
• Como indício aproximado da origem, dá para usar User-Agent: Miharu-Webhook/1.0 e os cabeçalhos X-Miharu-* (apenas como apoio).

8. Integrações

Gere uma URL de recebimento no seu serviço e cadastre-a no Miharu como URL do Webhook.

• Zapier: a URL de “Webhooks by Zapier” → “Catch Hook”
• Make: a URL de um “Custom webhook”
• n8n: a URL de um nó “Webhook”
• Seu próprio servidor: um endpoint que aceite o corpo JSON e devolva 2xx

9. Limitações

• Pelo Webhook chegam os alertas do sistema (as detecções) e as notificações do sistema.
• Diferenças ou textos longos podem ser cortados (por exemplo truncated: true).
• Com o filtro de notificações dá para limitar o envio a um grupo de monitoramento específico.

10. Solução de problemas

• A URL começa com https://?
• Seu endpoint está devolvendo 2xx? (Redirecionamentos e erros contam como falha.)
• O envio parou depois de várias respostas seguidas diferentes de 2xx? Confira o status no app e reconfigure para retomar.
• O processamento está levando mais de 10 segundos (tempo limite)? Devolva 2xx na hora e processe de forma assíncrona.

Envie suas observações e sugestões por “Comentários e sugestões” no app.