Webhook genérico

Visão geral

O webhook genérico aceita um JSON simples de qualquer sistema capaz de fazer um POST — scripts, CI/CD, jobs internos, ferramentas sem integração dedicada.


Tipo de fonte	`Genérico`
Mecanismo	`POST` JSON
Correlação	`externalId`
Auto-resolução	`"status": "resolved"` com o mesmo `externalId`

Se a sua ferramenta tem tipo de fonte dedicado (Grafana, Prometheus, Datadog, CloudWatch, Zabbix, New Relic), prefira esse tipo — o mapeamento de campos e a recuperação já vêm prontos. Use o genérico para scripts, monitores próprios e ferramentas sem integração dedicada.

1. Crie a fonte de alerta

Em Fontes de alerta, crie uma fonte do tipo Genérico. Copie a URL e o token.

2. Envie o alerta

curl -X POST "https://ingress.aciona.me/webhooks/<idDaFonte>" \
  -H "Content-Type: application/json" \
  -H "X-Aciona-Token: <tokenDaFonte>" \
  -d '{
    "externalId": "job-etl-noturno",
    "title": "Job de ETL noturno falhou",
    "description": "Saída com código 1 após 3 tentativas",
    "severity": "high",
    "service": "pipeline-dados",
    "status": "firing",
    "labels": { "env": "prod", "job": "etl-noturno" },
    "url": "https://ci.exemplo.com/builds/4821"
  }'

Resposta esperada: 202 Accepted.

Campos aceitos

Campo	Tipo	Obrigatório	Descrição
`title`	string	recomendado	Título do acionamento. Sem ele, vira `Untitled alert`.
`description`	string	não	Detalhe do problema.
`severity`	string	não	`critical`, `high`, `warning`, `info` ou sinônimos. Padrão: `warning`.
`service`	string	recomendado	Nome do serviço no aciona.me. Também aceito como `labels.service`.
`externalId`	string	recomendado; obrigatório na recuperação	Identificador estável do problema. É a chave de correlação.
`status`	string	não	`firing` ou `alerting` abrem; `resolved` resolve. Qualquer outro valor faz o alerta ser ignorado.
`labels`	objeto	não	Rótulos livres, preservados no acionamento.
`url`	string	não	Link de volta para a origem. Também aceito como `externalUrl`.

Se status estiver ausente, o alerta é tratado como disparo. firing, alerting e resolved não diferenciam maiúsculas de minúsculas. Qualquer outro valor — inclusive ok, normal, recovered ou closed — é aceito com 202, mas ignorado: nenhum acionamento é criado nem resolvido.

Agrupamento

Envios repetidos com o mesmo externalId para o mesmo serviço são agregados ao acionamento aberto, em vez de criar duplicatas. Use um externalId estável por problema — o nome do job, o identificador do check, a chave da regra.

Se você omitir externalId, a correlação recai sobre uma assinatura calculada a partir do conteúdo. Mudanças no título ou na descrição passam a gerar acionamentos separados. Sempre que possível, envie um externalId.

Recuperação automática

Quando o problema passa, envie o mesmo externalId com "status": "resolved". O aciona.me resolve sozinho o acionamento aberto por essa fonte — sem depender de uma pessoa. Exemplo: um monitor de ping abre um acionamento quando a API deixa de responder e, poucos minutos depois, avisa que ela voltou.

{
  "status": "firing",
  "externalId": "ping-api-principal",
  "title": "API principal não responde ao ping",
  "service": "api-principal",
  "severity": "critical"
}

{
  "status": "resolved",
  "externalId": "ping-api-principal"
}

Na recuperação, apenas status e externalId são necessários. Título, descrição e severidade podem ser enviados e podem ser diferentes da abertura; eles não são usados para encontrar o acionamento. service também não é necessário. O que acontece:

O acionamento passa para resolved em qualquer estado ativo — inclusive depois de alguém reconhecer ou assumir a responsabilidade. Não é preciso aprovar a resolução no painel.
A linha do tempo registra a resolução automática pelo webhook genérico, sem pessoa associada. Reconhecimento, responsável e histórico anteriores são preservados.
Escalonamentos e notificações pendentes são interrompidos. A recuperação não envia um aviso novo de resolução.
O acionamento é encerrado automaticamente 5 minutos depois da resolução, como nas demais integrações. Veja Resolver e encerrar.
Se o problema voltar — mesmo durante esses 5 minutos —, um novo firing abre um novo acionamento.

A recuperação exige um externalId válido (texto não vazio ou número). Sem ele, a requisição é recusada com 400 e nada é gravado. O aciona.me nunca resolve pelo título, pelo serviço ou pela assinatura do conteúdo. Para usar a recuperação, envie o externalId desde a abertura.

Boas práticas e limites

Mesma chave na abertura e na recuperação. O valor é comparado exatamente como enviado, sem ajuste de espaços ou de maiúsculas.
Uma chave por problema. Use identificadores diferentes para problemas ou serviços diferentes na mesma fonte: a recuperação não considera o serviço para desambiguar.
A correlação é por fonte. A recuperação só resolve acionamentos abertos pela mesma fonte de alerta, na mesma organização.
Recuperação sem acionamento aberto não faz nada. O 202 confirma que o alerta foi aceito, não que algo foi resolvido. Uma recuperação repetida é ignorada.
Recuperação atrasada. Se a mesma chave for reutilizada, uma recuperação antiga que chegue depois de uma nova queda pode resolver a nova ocorrência. Para evitar isso, use uma chave por episódio (por exemplo, ping-api-principal-2026-10-15T10:00), estável entre a abertura, as repetições e a recuperação desse episódio.
Ordem em rajadas. Em picos de volume, uma recuperação pode ser processada antes da abertura correspondente; nesse caso ela não encontra o acionamento e o disparo seguinte fica aberto. Espaçe o envio da recuperação ou resolva pelo painel.
Eventos antigos não são reprocessados. Recuperações enviadas antes deste recurso foram descartadas e não resolvem nada retroativamente.

Exemplos

curl -X POST "https://ingress.aciona.me/webhooks/$ACIONA_SOURCE_ID" \
  -H "Content-Type: application/json" \
  -H "X-Aciona-Token: $ACIONA_TOKEN" \
  -d "{\"externalId\":\"backup-diario\",\"title\":\"Backup diário falhou\",\"severity\":\"critical\",\"service\":\"banco-principal\",\"status\":\"firing\"}"

import os
import requests

requests.post(
    f"https://ingress.aciona.me/webhooks/{os.environ['ACIONA_SOURCE_ID']}",
    headers={"X-Aciona-Token": os.environ["ACIONA_TOKEN"]},
    json={
        "externalId": "backup-diario",
        "title": "Backup diário falhou",
        "description": "pg_dump retornou código 2",
        "severity": "critical",
        "service": "banco-principal",
        "status": "firing",
        "labels": {"env": "prod"},
    },
    timeout=10,
)

await fetch(
  `https://ingress.aciona.me/webhooks/${process.env.ACIONA_SOURCE_ID}`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Aciona-Token': process.env.ACIONA_TOKEN,
    },
    body: JSON.stringify({
      externalId: 'backup-diario',
      title: 'Backup diário falhou',
      severity: 'critical',
      service: 'banco-principal',
      status: 'firing',
    }),
  },
);

- name: Acionar o time em caso de falha
  if: failure()
  run: |
    curl -X POST "https://ingress.aciona.me/webhooks/${{ secrets.ACIONA_SOURCE_ID }}" \
      -H "Content-Type: application/json" \
      -H "X-Aciona-Token: ${{ secrets.ACIONA_TOKEN }}" \
      -d '{
        "externalId": "deploy-${{ github.repository }}",
        "title": "Deploy falhou em ${{ github.repository }}",
        "severity": "high",
        "service": "plataforma",
        "status": "firing",
        "url": "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
      }'

Solução de problemas

Respondeu 202 mas nenhum acionamento apareceu

O campo status provavelmente tem um valor diferente de firing, alerting ou resolved — nesse caso o alerta é aceito e descartado. Envie firing ou omita o campo. Se foi uma recuperação (resolved), ela nunca cria acionamento.

A recuperação respondeu 400

Falta o externalId ou ele está vazio, só com espaços ou não é texto/número. Envie o mesmo externalId usado na abertura.

Acionamentos duplicados

O externalId está mudando entre os envios (por exemplo, incluindo um timestamp). Use um identificador estável por problema.

Acionamento sem serviço ou sem responsável

O campo service não bate com nenhum serviço da organização, ou o serviço não tem time responsável com escala ativa.

A recuperação não resolveu o acionamento

Confira se o externalId é exatamente o mesmo da abertura e se a recuperação foi enviada para a mesma fonte. Acionamentos abertos sem externalId não são resolvidos de forma confiável pelo webhook — resolva pelo painel ou pelo app.

Fontes de alerta

Guias por ferramenta

Visão geral

1. Crie a fonte de alerta

2. Envie o alerta

Campos aceitos

Agrupamento

Recuperação automática

Boas práticas e limites

Exemplos

Solução de problemas

Referência completa do payload

​Visão geral

​1. Crie a fonte de alerta

​2. Envie o alerta

​Campos aceitos

​Agrupamento

​Recuperação automática

​Boas práticas e limites

​Exemplos

​Solução de problemas

Referência completa do payload

Visão geral

1. Crie a fonte de alerta

2. Envie o alerta

Campos aceitos

Agrupamento

Recuperação automática

Boas práticas e limites

Exemplos

Solução de problemas