---
title: "Alertas do Google Cloud Monitoring por ligação via webhook"
description: "O Cloud Monitoring manda e-mail, SMS e push, mas não liga. Envie as políticas de alertas do GCP a um webhook de ligação: configuração, campos e filtros."
date: 2026-11-15
author: Nooc
authorAvatarLink: /images/avatars/nooc.webp
authorLink: https://nooc.me
tags:
  - Google Cloud
  - Cloud Monitoring
  - GCP
  - alertas por ligação
  - webhooks
  - plantão
---

# Alertas do Google Cloud Monitoring por ligação: da política de alertas ao telefone tocando

O Google Cloud Monitoring não consegue ligar para o seu telefone. Os canais de notificação dele são e-mail, SMS, o app para dispositivos móveis do Google Cloud, Slack, Google Chat, PagerDuty, Pub/Sub e webhooks — e a própria documentação do Google avisa que o SMS não é totalmente confiável e pode não estar disponível na sua região. Se você quer que uma política de alertas toque como uma chamada recebida, o caminho mais curto é um canal de webhook apontado para um canal de ligação do Echobell, com duas linhas de template e uma condição.

Este guia cobre o canal, o webhook, os campos que o Cloud Monitoring realmente envia no payload, como fazer os incidentes "open" tocarem e os "closed" ficarem quietos, e as configurações da política de alertas que decidem com que frequência o seu telefone toca.

## Por que os canais nativos não bastam às 3 da manhã

- **O e-mail** espera você olhar.
- **O SMS**, nas palavras do Google, não é um tipo de canal totalmente confiável, e pode não ser oferecido no seu país. Além disso, o Não Perturbe silencia o SMS como qualquer outra mensagem.
- **O app para dispositivos móveis** envia um push comum. Ele aparece na tela bloqueada; não fica tocando.
- **O PagerDuty** consegue ligar para você, mas é uma plataforma de plantão completa, com configuração e contrato próprios.

Um canal de webhook, por outro lado, alcança qualquer coisa com um endpoint HTTPS público, e o Cloud Monitoring envia a ele um documento JSON estruturado para cada incidente. É tudo de que o Echobell precisa.

## O que você precisa

- Um projeto do Google Cloud com pelo menos uma política de alertas (ou uma verificação de tempo de atividade sobre a qual você quer ser alertado)
- Permissão para editar canais de notificação (`roles/monitoring.notificationChannelEditor` ou Monitoring Editor)
- Echobell instalado ([App Store](https://apps.apple.com/app/apple-store/id6743597198?pt=128151925&ct=blog-google-cloud-monitoring-phone-call-alerts-pt&mt=8) / [Google Play](https://play.google.com/store/apps/details?id=one.echobell.echobellandroid))
- Dez minutos

Nada no seu projeto precisa aceitar tráfego de entrada. Quem faz a requisição de saída é o Cloud Monitoring.

## Passo 1 — Crie um canal que toca

No Echobell, crie um canal e defina o tipo de notificação como **Ligação**. Um canal de ligação se comporta como uma chamada recebida em vez de um push, então ocupa a tela e toca. Com o modo Foco ou o Não Perturbe do iOS ativado, ele só toca se as suas configurações de Foco permitirem chamadas.

Abra as **Configurações avançadas** do canal e ative **Modelo personalizado**. O Cloud Monitoring embrulha tudo num objeto `incident`, então os templates leem campos aninhados:

```
Título: {{incident.state}}: {{incident.policy_name}}
Corpo: {{incident.summary}}
```

Defina o **template de link** para que tocar na notificação abra o incidente no console do Google Cloud:

```
{{incident.url}}
```

Adicione uma **condição** para que só os incidentes recém-abertos toquem:

```
incident.state == "open"
```

Copie a URL do webhook do canal na tela de detalhes:

```
https://hook.echobell.one/t/<channel-token>
```

## Passo 2 — Adicione um canal de notificação de webhook no Google Cloud

1. Abra **Monitoring → Alerting** e clique em **Edit notification channels**
2. Em **Webhooks**, clique em **Add new**
3. **Endpoint URL**: a URL do seu canal do Echobell do passo 1
4. **Display name**: `Echobell (call)`
5. Deixe **Use HTTP Basic Auth** desativado
6. Clique em **Test connection** e depois em **Save**

Deixe o Basic Auth desativado de propósito. O handshake de Basic Auth do Google espera que o endpoint responda à primeira requisição com um `401` e um cabeçalho `WWW-Authenticate`; o Echobell, em vez disso, autentica pelo token secreto da URL, então trate essa URL como uma senha.

Se você gerencia os canais com Terraform, o mesmo canal fica assim:

```hcl
resource "google_monitoring_notification_channel" "echobell_call" {
  display_name = "Echobell (call)"
  type         = "webhook_tokenauth"

  labels = {
    url = "https://hook.echobell.one/t/<channel-token>"
  }
}
```

Mantenha o token fora do controle de versão: leia-o de uma variável ou do Secret Manager em vez de commitar a URL.

## Passo 3 — Vincule o canal às políticas que merecem uma ligação

Abra uma política de alertas, vá até **Notifications and name** e adicione `Echobell (call)` em **Notification channels**. Uma política pode notificar vários canais ao mesmo tempo, então mantenha o seu canal de e-mail ou de Slack ao lado.

Seja exigente aqui. Este é o filtro de verdade: um canal vinculado só a "a API de produção caiu" e "o banco de dados ficou sem disco" toca raramente o bastante para você continuar atendendo. Deixe "CPU acima de 70% por cinco minutos" no e-mail.

Duas configurações na mesma página definem o que chega ao seu telefone:

- **Notify on incident closure.** Com ela ativada, o Cloud Monitoring também envia uma notificação quando o incidente é fechado. A condição `incident.state == "open"` do passo 1 impede que essa toque; o passo 6 mostra como recebê-la em silêncio.
- **Incident autoclose duration.** Se a métrica parar de enviar dados, os incidentes abertos são fechados depois desse período. Deixe o valor padrão, a menos que tenha um motivo para mudar.

## Passo 4 — Saiba como o payload é de verdade

O Cloud Monitoring envia por padrão a versão 1.2 do esquema. Reduzido aos campos que você provavelmente vai usar, um incidente aberto fica assim:

```json
{
  "version": "1.2",
  "incident": {
    "incident_id": "0.opqiw61fsv7p",
    "scoping_project_id": "my-project",
    "url": "https://console.cloud.google.com/monitoring/alerting/incidents/0.opqiw61fsv7p?project=my-project",
    "state": "open",
    "renotify": false,
    "started_at": 1794713564,
    "ended_at": null,
    "policy_name": "Prod API 5xx rate",
    "condition_name": "5xx ratio above 5%",
    "resource_display_name": "prod-api",
    "threshold_value": "0.05",
    "observed_value": "0.183",
    "severity": "Critical",
    "policy_user_labels": {
      "team": "payments"
    },
    "documentation": {
      "content": "Check the latest deploy first. Runbook: https://wiki.example.com/api-5xx",
      "mime_type": "text/markdown"
    },
    "summary": "5xx ratio for prod-api with metric labels {response_code_class=500} is above the threshold of 0.050 with a value of 0.183."
  }
}
```

O que vale saber antes de editar um template:

- **Tudo fica dentro de `incident`.** `{{policy_name}}` sai vazio; `{{incident.policy_name}}`, não.
- **`state` é `open` ou `closed`.** É desse único campo que dependem a condição e o template de título.
- **`summary` é texto gerado.** O Google não garante um formato estável, então exiba-o, mas não compare com ele numa condição.
- **Campos podem faltar.** O Google observa que alguns campos ficam ausentes ou null dependendo da política e do estado do incidente. No Echobell, um campo ausente é renderizado como string vazia, então o template continua funcionando; só não monte uma condição sobre um campo que as suas políticas não preenchem.
- **`documentation.content` é seu.** O que você digitar na caixa **Documentation** da política chega aqui. Uma instrução de uma linha ("Verifique primeiro o último deploy") é mais útil num telefone tocando do que o resumo gerado.
- **A gravidade segue a política.** É o nível que você definiu na política. Mande para si mesmo um incidente de teste e confira o valor exato antes de filtrar por ele.

Um corpo que começa com as suas próprias palavras e recorre ao resumo:

```
{{incident.documentation.content}}
{{incident.summary}}
```

## Passo 5 — Decida o que toca e com que frequência

A maior parte da filtragem já aconteceu quando você escolheu quais políticas recebem o canal. A condição do canal do Echobell cuida do resto.

| Objetivo | Condição |
| --- | --- |
| Tocar só quando um incidente abre | `incident.state == "open"` |
| Tocar uma vez, não a cada lembrete | `incident.state == "open" && !incident.renotify` |
| Tocar só para as políticas de um time | `incident.state == "open" && incident.policy_user_labels.team == "payments"` |
| Tocar só de madrugada (00:00–07:00 UTC) | `incident.state == "open" && hour < 7` |

**Lembretes.** Uma política pode reenviar notificações enquanto o incidente continuar aberto: na API é `alertStrategy.notificationChannelStrategy[].renotifyInterval`, de 30 minutos a 24 horas. Essas repetições chegam com `renotify: true`. Se elas devem tocar é uma escolha: tocar de novo é um escalonamento rudimentar, mas eficaz, para um incidente que ninguém resolveu, e pulá-las evita que uma interrupção longa toque a noite inteira. A segunda linha da tabela faz esse pulo.

**Rótulos de usuário.** Os rótulos de usuário da política, como `team: payments`, vêm em `policy_user_labels`. Uma condição sobre eles faz um canal vinculado a muitas políticas tocar para algumas e ficar quieto para as demais. Eles filtram, não roteiam: cada URL de webhook sempre aciona o mesmo canal do Echobell, então um rótulo não consegue mandar um incidente para o canal de outra pessoa.

As variáveis de hora do Echobell são em UTC, então converta do seu fuso primeiro. A [referência de condições](/pt/docs/conditions) lista todas as variáveis.

## Passo 6 — Dê aos fechamentos uma porta mais silenciosa

Com **Notify on incident closure** ativado, um incidente fechado é uma boa notícia que vale ver, mas não vale um toque. Crie um segundo canal do Echobell do tipo **Urgente (Time Sensitive)** (ou normal) com os mesmos templates e sem condição, adicione-o no Google Cloud como um segundo canal de webhook e vincule os dois à política. O template de título já se lê como "closed: Prod API 5xx rate".

| Canal do Echobell | Condição | Tipo de canal | Comportamento |
| --- | --- | --- | --- |
| `gcp-call` | `incident.state == "open"` | Ligação | Toca como uma chamada recebida |
| `gcp-log` | nenhuma | Urgente ou Normal | Cada abertura, lembrete e fechamento, sem tocar |

## Teste antes de confiar

**Teste primeiro o lado do Echobell.** Envie um payload no formato do Cloud Monitoring:

```bash
curl -X POST https://hook.echobell.one/t/<channel-token> \
  -H 'Content-Type: application/json' \
  -d '{"version":"1.2","incident":{"state":"open","renotify":false,"policy_name":"Manual test","summary":"Testing the Echobell path","url":"https://console.cloud.google.com/monitoring/alerting"}}'
```

**Depois teste o lado do Google.** O botão **Test connection** envia um payload de exemplo cujos campos não são de um incidente real, então ele pode não passar na sua condição. Para um teste de ponta a ponta, crie uma política descartável com um limite que você já ultrapassa — por exemplo, utilização de CPU da VM acima de 1% —, vincule `Echobell (call)`, espere disparar e depois exclua a política.

Se o `curl` toca e a política real não, o problema está do lado do Google — o canal não está vinculado, a condição ainda não foi atendida pela duração definida ou a URL do endpoint foi copiada errada —, não no canal do Echobell.

## Alertas baseados em registros e verificações de tempo de atividade

- **As verificações de tempo de atividade** não notificam ninguém sozinhas; elas alimentam uma política de alertas. Crie a política a partir da verificação e vincule o mesmo canal de webhook.
- **As políticas de alertas baseadas em registros** só notificam quando um incidente abre — o Google não envia notificação de fechamento para elas — e exigem um limite de taxa de notificações, que restringe com que frequência uma linha de log barulhenta pode fazer você tocar. A condição `incident.state == "open"` continua funcionando; o canal de fechamentos simplesmente nunca recebe nada dessas políticas.

## Limites que importam durante um incidente

- **Corpo de 1 MiB.** O Echobell rejeita com HTTP 413 corpos de gatilho acima de 1 MiB. Um incidente do Cloud Monitoring tem poucos kilobytes.
- **120 requisições por minuto por token.** Acima disso, o gatilho responde `429` com `RATE_LIMIT_EXCEEDED` e um `Retry-After`. Uma única política raramente chega perto, mas dezenas de políticas disparando ao mesmo tempo durante uma interrupção regional podem chegar — mais um motivo para manter curta a lista do canal de ligação.
- **1500 bytes de corpo de notificação.** Renderizações mais longas são truncadas. Mantenha a documentação da política curta, ou coloque nela o link para o runbook em vez do runbook inteiro.

## O que essa configuração não oferece

- **Sem reconhecimento.** Atender a ligação não reconhece nem fecha o incidente no Google Cloud.
- **Sem escalonamento nem rodízio.** Todos os inscritos no canal recebem a ligação; ninguém é chamado depois.
- **Sem deduplicação além do incidente.** Uma condição instável abre um incidente novo a cada vez, e cada um toca. Resolva na política com uma janela de duração mais longa.

Se isso for inaceitável, você precisa de uma plataforma de plantão completa. Se o que você precisa é "me liga quando a política de produção disparar", são duas telas no console.

## Solução de problemas

**O incidente abriu mas nada chegou.** Abra o incidente em **Monitoring → Alerting** e confira se a política lista o canal de webhook. Garanta que a URL do endpoint é a URL completa do Echobell, com o token.

**A notificação chegou mas não tocou.** O tipo de canal não é **Ligação**, ou as configurações de Foco do seu telefone não deixam as chamadas passarem. Verifique o canal e a sua configuração de Foco.

**A notificação está em branco.** O template está lendo campos de nível superior. Adicione o prefixo `incident.` — `{{incident.policy_name}}`, não `{{policy_name}}`.

**Toca de novo a cada meia hora.** A política tem um intervalo de renotificação. Remova-o, ou adicione `!incident.renotify` à condição.

**Toca quando o incidente fecha.** Falta `incident.state == "open"` na condição, ou ela está no canal errado.

## Perguntas frequentes

### O Google Cloud Monitoring consegue ligar para um número de telefone nativamente?

Não. Os canais de notificação são e-mail, SMS, o app para dispositivos móveis do Google Cloud, Slack, Google Chat, PagerDuty, Pub/Sub e webhooks. Uma chamada de voz exige um serviço externo: uma plataforma de plantão ou um webhook de ligação como o Echobell.

### Preciso de Pub/Sub ou de uma Cloud Function?

Não. O próprio Cloud Monitoring envia o incidente para a URL do webhook. O Pub/Sub é a recomendação do Google para endpoints que não são públicos; o endpoint do Echobell é público, então o canal de webhook basta.

### Um alerta do Cloud Monitoring atravessa o Não Perturbe?

Só se chegar como alerta em formato de ligação. Um canal do Echobell do tipo ligação se comporta como uma chamada recebida, e isso o modo Foco e o Não Perturbe do iOS deixam passar quando as suas configurações de Foco permitem chamadas. Um SMS ou um push comum, não. Ative também **Repetir chamada com falha**: com “Permitir Ligações Repetidas” ativado nas configurações de Foco, uma segunda chamada em até três minutos pode tocar.

### Devo usar a opção Basic Auth no webhook?

Não. O Echobell autentica pelo token da URL. O fluxo de Basic Auth do Google espera primeiro um desafio `401`, que o Echobell não envia.

### Posso ligar para pessoas diferentes conforme a política?

Sim. Crie um canal do Echobell por público, adicione a URL de cada canal ao Google Cloud como um canal de webhook próprio e vincule cada um às políticas pelas quais aquele público responde. Uma URL de webhook sempre aciona o mesmo canal do Echobell, então uma condição com `policy_user_labels` pode silenciar políticas nesse canal, mas não passá-las para outro. Não há reconhecimento, então todos os inscritos com "ligação" recebem a chamada.

### E com vários projetos?

Um canal de notificação pertence a um único projeto. Crie o canal de webhook em cada projeto — a mesma URL do Echobell funciona em todos — ou alerte a partir de um projeto de escopo que monitore os outros.

## Fechando

O caminho tem quatro partes: um canal de ligação com a condição `incident.state == "open"`, um canal de notificação de webhook apontado para ele, uma lista curta de políticas que merecem uma ligação e um teste real antes de confiar. O resto é manter essa lista curta o bastante para que, daqui a um mês, o toque ainda signifique alguma coisa.

[Baixe o Echobell para iPhone](https://apps.apple.com/app/apple-store/id6743597198?pt=128151925&ct=blog-google-cloud-monitoring-phone-call-alerts-pt&mt=8) ou [pegue no Google Play](https://play.google.com/store/apps/details?id=one.echobell.echobellandroid) e depois aponte para ele a sua política de alertas mais importante.

## Artigos relacionados

- [Referência de condições de canal](/pt/docs/conditions)
- [Referência de templates](/pt/docs/template)
- [Guia de integração com webhooks](/pt/docs/webhook)
- [Alarmes do CloudWatch por ligação](/pt/blog/cloudwatch-alarm-phone-call-alerts)
- [Alertas do Alertmanager por chamada](/pt/blog/alertmanager-phone-call-alerts)
- [Guia do desenvolvedor para a fadiga de alertas](/pt/blog/fix-alert-fatigue-developer-guide)
- [Furando o modo Foco do iOS para alertas críticos](/pt/blog/how-to-bypass-ios-focus-mode-for-critical-alerts)
