--- title: Notificações diretas - Chaves de API pessoais para alertas instantâneos sidebarTitle: Direct description: Envie notificações diretamente com uma chave de API pessoal - sem configurar canais. Crie chaves diretas e acione alertas instantâneos com título, corpo e links. --- # Notificações diretas 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 | | Direct | Canais | |---|---|---| | **Configuração** | Crie uma chave e use a URL | Crie um canal e configure modelos | | **Público** | Só você | Qualquer pessoa que se inscrever | | **Modelos** | Nenhum — você define título e corpo em cada requisição | Modelos configuráveis com variáveis | | **Condições** | Nenhuma | Entrega condicional suportada | | **Ideal para** | Scripts pessoais, alertas rápidos, automação | Alertas compartilhados, fluxos de trabalho estruturados | ## 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`: ```http 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: ```http 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: ```http 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: ```json { "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. | Campo | Tipo | Obrigatório | Descrição | |---|---|---|---| | `title` | string | Não | Título da notificação. O padrão é "Direct Notification" quando omitido. | | `body` | string | Não | Texto do corpo da notificação. | | `externalLink` | string | Não | Um link clicável exibido no registro da notificação. | | `notificationType` | string | Não | Nível de urgência da notificação. Aceita `active`, `time-sensitive` ou `calling`. O padrão é `active`. Veja [Tipos de notificação](#tipos-de-notificação). | ### Tipos de notificação Você pode controlar o nível de urgência das notificações do Direct com o campo `notificationType`: | Tipo | Descrição | |---|---| | `active` | Notificação normal, entregue da forma padrão. Este é o valor padrão. | | `time-sensitive` | Notificação de alta prioridade, capaz de atravessar os modos de Foco. | | `calling` | Alerta em formato de chamada para situações críticas. **Exige uma assinatura premium ativa.** Sem o premium, o envio recai para `time-sensitive`. | Exemplo com tipo de notificação: ```http 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: ```json { "success": true, "message": "Notification triggered successfully." } ``` Se a chave for inválida ou não for encontrada (observe que isso ainda retorna HTTP `200`): ```json { "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 ```bash # 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 ```bash # 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 ```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 ```javascript 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 ```yaml - 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](#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: ```bash 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](/docs/support) 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](/docs/webhook)** — Para notificações compartilhadas e baseadas em modelos, com canais - **[Sintaxe de modelos](/docs/template)** — Aprenda sobre os modelos de notificação dos canais - **[Gatilhos por e-mail](/docs/email-trigger)** — Acione notificações por e-mail - **[Explore as integrações](/docs/features)** — Conecte-se às ferramentas que você já usa