Notificações diretas - Chaves de API pessoais para alertas instantâneos

As notificações diretas permitem que você envie alertas pessoais por meio de uma URL de webhook simples — sem configuração de canal, sem modelos, sem inscritos. Basta criar uma chave, chamar a URL e receber a notificação instantaneamente no seu dispositivo.

O que é o Direct?

Os canais são ótimos para notificações estruturadas e baseadas em modelos, que podem ser compartilhadas com outras pessoas. Mas às vezes você só quer uma notificação rápida e pessoal — um build terminou, um script foi concluído, um sensor foi acionado. O Direct foi feito exatamente para isso.

Com o Direct, você recebe uma chave de API pessoal que corresponde a uma URL de webhook exclusiva. Quando você chama essa URL com um título e um corpo, uma notificação é enviada diretamente para você. Nenhuma configuração de canal é necessária.

Quando usar o Direct e quando usar canais

Primeiros passos

1. Crie uma chave direta

No app Echobell, toque em Direct no topo da sua lista de canais. Em seguida, toque em Criar para gerar uma nova chave direta. Dê a ela um nome descritivo (por exemplo, "Servidor de build", "Home Lab", "Bot de trading").

2. Copie a URL do webhook

Cada chave direta tem uma URL de webhook exclusiva neste formato:

https://hook.echobell.one/d/{your-key-token}

Você encontra e copia essa URL na tela de detalhes da chave direta, dentro do app. O token fica oculto por padrão, por segurança — toque para exibi-lo.

3. Envie uma notificação

Chame a URL do webhook com um corpo JSON contendo title e body:

POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Build Complete",
  "body": "Project X built successfully in 3m 42s"
}

Pronto — você vai receber uma notificação imediatamente.

Fazendo requisições

Requisição POST (recomendada)

Envie um corpo JSON com o conteúdo da sua notificação:

POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Deployment Status",
  "body": "v2.1.0 deployed to production",
  "externalLink": "https://dashboard.example.com/deploys/latest"
}

Requisição GET

Você também pode passar parâmetros pela query string:

GET https://hook.echobell.one/d/YOUR_KEY_TOKEN?title=Alert&body=CPU+at+95%25

Somente POST

Cada chave direta tem sua própria configuração Somente POST no app Echobell. Ela vem desativada por padrão.

Quando está ativada, apenas POST pode acionar essa chave. Um GET para a URL de webhook dela é rejeitado com 405 Method Not Allowed, e nenhuma notificação é enviada:

{
  "success": false,
  "notificationTriggered": false,
  "message": "This trigger only accepts POST requests; GET triggering is disabled in its settings."
}

Requisições HEAD não são afetadas — elas respondem 200 e nunca acionam uma notificação, com Somente POST ativado ou desativado.

A configuração é por chave, então você pode manter uma chave compatível com GET para comandos de uma linha no shell e uma chave somente POST para URLs que acabam coladas em conversas de chat ou páginas de wiki.

Campos da requisição

Todos os nomes de campos são insensíveis a maiúsculas e minúsculas — title, Title e TITLE são tratados da mesma forma, seja no corpo JSON ou na query string.

Tipos de notificação

Você pode controlar o nível de urgência das notificações do Direct com o campo notificationType:

Exemplo com tipo de notificação:

POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Server Down",
  "body": "Production server is unresponsive",
  "notificationType": "calling"
}

Formato da resposta

Uma requisição bem-sucedida retorna:

{
  "success": true,
  "message": "Notification triggered successfully."
}

Se a chave for inválida ou não for encontrada (observe que isso ainda retorna HTTP 200):

{
  "success": false,
  "message": "Direct key not found."
}

Gerenciando chaves diretas

Várias chaves

Você pode criar várias chaves diretas para finalidades diferentes:

• "Servidor de CI" — para notificações de build e implantação
• "Automação residencial" — para alertas de sensores IoT
• "Cron jobs" — para resultados de tarefas agendadas
• "Bot de trading" — para alertas de mercado

Cada chave tem sua própria URL de webhook independente. Os registros de notificação são associados automaticamente à chave que os acionou, então fica fácil identificar qual serviço enviou cada notificação.

Redefinir o token

Se a URL de webhook de uma chave for comprometida, você pode redefinir o token na tela de detalhes da chave. Isso gera uma nova URL e invalida a antiga imediatamente. Atualize os scripts ou serviços que usam a URL antiga.

Excluir uma chave

Excluir uma chave direta invalida permanentemente a URL de webhook dela. Qualquer requisição para a URL antiga vai falhar.

Casos de uso comuns

Scripts de shell

# Notify when a long-running task finishes
./run-migration.sh && \
curl -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"title": "Migration Complete", "body": "Database migration finished successfully"}'

Cron jobs

# In crontab: notify on backup completion
0 2 * * * /usr/local/bin/backup.sh && curl -s -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN -H "Content-Type: application/json" -d '{"title": "Backup Done", "body": "Nightly backup completed"}'

Python

import requests

requests.post(
    "https://hook.echobell.one/d/YOUR_KEY_TOKEN",
    json={
        "title": "Training Complete",
        "body": f"Model accuracy: {accuracy:.2%}",
        "externalLink": "https://wandb.ai/runs/abc123"
    }
)

Node.js

await fetch("https://hook.echobell.one/d/YOUR_KEY_TOKEN", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "Deploy Complete",
    body: `Version ${version} deployed to production`,
  }),
});

GitHub Actions

- name: Notify via Echobell Direct
  if: always()
  env:
    ECHOBELL_DIRECT_URL: ${{ secrets.ECHOBELL_DIRECT_URL }}
  run: |
    curl -X POST "$ECHOBELL_DIRECT_URL" \
      -H "Content-Type: application/json" \
      -d '{"title": "Build ${{ job.status }}", "body": "${{ github.repository }} @ ${{ github.sha }}"}'

Boas práticas

Segurança

• Trate as URLs das chaves diretas como segredos — qualquer pessoa com a URL pode enviar notificações para você
• Use variáveis de ambiente para guardar os tokens das chaves em scripts e em CI/CD
• Redefina os tokens assim que suspeitar que uma chave foi comprometida
• Crie chaves separadas para serviços diferentes, para poder revogar cada uma individualmente

Organização

• Dê nomes descritivos às chaves — você vai se agradecer quando estiver gerenciando várias delas
• Use uma chave por serviço — isso facilita identificar a origem das notificações e revogar acessos
• Exclua as chaves que não usa — reduza sua superfície de ataque

Tratamento de erros

Ao integrar o Direct aos seus scripts, decida com base no campo success do JSON, e não no status HTTP:

• 200 OK: a requisição foi recebida. Confira o corpo JSON: success: true significa que a notificação foi acionada; success: false significa que não foi. Uma chave direta desconhecida ou redefinida retorna HTTP 200 com { "success": false, "message": "Direct key not found." } — e não um 404.
• 400 Bad Request: o token da chave tem o comprimento errado. Corrija a URL.
• 405 Method Not Allowed: a chave está com Somente POST ativado e a requisição não era um POST. Mude o chamador para POST ou desative a configuração.

O Echobell não aplica limite de taxa às chamadas do Direct, então não existe resposta 429.

Privacidade e segurança

O que é armazenado

• Nos nossos servidores:

  • Metadados da chave direta (nome, token com hash, proprietário)
  • O payload da requisição é processado e armazenado temporariamente para a entrega

• No seu dispositivo:

  • Conteúdo da notificação (título e corpo)
  • Histórico de acionamentos e horários
  • Links externos

O que não é armazenado

• Não retemos permanentemente os payloads das requisições depois da entrega
• Não analisamos o conteúdo das notificações
• Não compartilhamos seus dados com terceiros

Solução de problemas

Não estou recebendo notificações

1. Confira a URL do webhook — copie-a diretamente do app e verifique se não há espaços a mais
2. Verifique se a chave ainda existe — ela pode ter sido excluída ou ter tido o token redefinido
3. Garanta as permissões de notificação — o app Echobell precisa de permissão para enviar notificações no seu dispositivo
4. Teste com o curl — para descartar problemas com o seu cliente HTTP:

   curl -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN \
     -H "Content-Type: application/json" \
     -d '{"title": "Test", "body": "Hello from Direct"}'

Erros de requisição

• Erro ao interpretar o JSON: verifique se o cabeçalho Content-Type: application/json está definido e se o corpo é um JSON válido
• Chave não encontrada: um corpo com "success": false e "Direct key not found." significa que o token foi redefinido ou a chave foi excluída (o status HTTP continua sendo 200)

Ainda com problemas?

• Acesse nossa Central de suporte para obter mais ajuda
• Fale com a gente pelo e-mail echobell@weelone.com informando:
  • Descrição do problema
  • Exemplo de requisição (com o token ocultado)
  • Comportamento esperado e comportamento observado

Próximos passos

• Integração com webhooks — Para notificações compartilhadas e baseadas em modelos, com canais
• Sintaxe de modelos — Aprenda sobre os modelos de notificação dos canais
• Gatilhos por e-mail — Acione notificações por e-mail
• Explore as integrações — Conecte-se às ferramentas que você já usa