Canais de entrega pessoal

Canais de entrega pessoal enviam suas próprias notificações Kanera para outro lugar que não seja e-mail ou push do navegador.

O push de e-mail e navegador funcionam bem para a maioria das pessoas, mas não são os únicos destinos úteis. Algumas equipes já executam um servidor de notificação auto-hospedado. Algumas pessoas desejam alertas em um telefone sem conceder permissão de notificação do navegador. Alguns querem que os eventos Kanera cheguem a um script, um painel inicial ou uma ferramenta de plantão.

Kanera oferece suporte a três destinos pessoais:

Canal	O que é isso	Bom para
ntfy	Um servidor de notificação que você assina em um aplicativo de telefone ou desktop, ntfy.sh ou sua própria instância.	Alertas de telefone sem push do navegador, tópicos de equipe compartilhados, configurações de homelab.
Gotificar	Um servidor de notificação auto-hospedado com seu próprio aplicativo Android e interface da web.	Alertas totalmente auto-hospedados, sem serviço push de terceiros no caminho.
Webhook pessoal	Um endpoint HTTPS de sua propriedade, recebendo JSON assinado.	Scripts, painéis, roteamento de plantão, automação personalizada, pontes de bate-papo que você já executa.

Esses canais são pessoais. Eles pertencem à sua conta, não a um espaço de trabalho, e ninguém mais pode vê-los ou alterá-los. Eles não dependem da configuração push da organização ou da permissão de notificação do navegador.

Eles precisam Pro ou os 30 dias Avaliação profissional. Eles não estão disponíveis no Free hospedado, onde o e-mail, o push do navegador e a gaveta do aplicativo continuam funcionando normalmente. Veja Requisitos do plano abaixo.

Se você quiser que toda a equipe veja a atividade do cartão em um canal compartilhado, use Destinos de bate-papo em vez disso. Canais pessoais são feeds privados; os destinos de bate-papo são um feed de equipe e são configurados por um administrador do espaço de trabalho.

Quando usar cada canal

Usar ntfy quando você deseja alertas por telefone ou desktop e prefere não usar o push do navegador. Instale o aplicativo ntfy, assine um tópico e Kanera publica nele. Esta também é a opção mais simples se você já publicou outros alertas no ntfy e deseja Kanera ao lado deles.

Usar Gotificar quando o requisito é que nada saia da sua infraestrutura. O Gotify é executado em seu próprio servidor, o aplicativo Android se comunica diretamente com ele e o Kanera só precisa da URL do servidor e de um token do aplicativo.

Use um webhook pessoal quando você quiser fazer algo com a notificação em vez de lê-la. Usos comuns:

• Encaminhe menções e cartões vencidos para uma ferramenta de plantão ou pager.
• Publique suas tarefas em um canal de bate-papo pessoal ou em um bot que você já administra.
• Anexe notificações a um log, painel ou banco de dados pessoal.
• Faça a ponte entre Kanera e um provedor de notificação que Kanera não suporta diretamente.

Requisitos do plano

Os canais de entrega pessoal precisam do Pro ou de uma avaliação Pro. E-mail, push do navegador, gaveta de notificações no aplicativo, resumo diário, visualização e Regras do espaço de trabalho estão disponíveis em todos os planos e não são afetados por isso.

Em hospedagem gratuita, Destinos de notificação adicionais mostra ntfy, Gotify e webhooks pessoais não estão disponíveis no seu plano em vez dos cartões de configuração.

Se uma organização mudar do Pro ou de avaliação para o Gratuito, Kanera desligará os canais ntfy, Gotify e webhook de cada pessoa. Nada é excluído: URLs de servidor, tópicos, tokens, segredos de assinatura e preferências por tipo permanecem salvos, e qualquer coisa que ainda esteja esperando para ser enviada é descartada em vez de chegar atrasada. A atualização novamente ativa exatamente os canais que cada pessoa ativou, para que ninguém precise reconectar nada.

Onde configurá-los

Abrir Configurações de perfil -> Notificações e expandir Destinos de notificação adicionais.

Cada canal possui seu próprio cartão com campos de conexão, um Habilitado alternar, alternar o tipo de notificação e Salvar, Testee Remover ações.

Um canal não pode ser ativado até que você preencha tudo o que ele precisa. O que você permite aqui é o máximo que um canal lhe enviará: Regras do espaço de trabalho pode silenciar um canal para um espaço de trabalho, mas nunca fazê-lo enviar mais do que essas configurações permitem.

Sua gaveta de notificações no aplicativo nunca é afetada por essas configurações. Sempre mostra o feed completo.

Configurar o ntfy

1. Escolha o servidor. Usar https://ntfy.sh para o serviço público, ou sua própria instância como https://ntfy.example.com.
2. Escolha um nome de tópico. Trate-o como segredo de serviço público, pois qualquer pessoa que conheça o assunto pode assiná-lo. Algo como kanera-a7f3c2-amelia é melhor do que kanera.
3. Em Kanera, insira o URL do servidor e Tópico. Deixe a string de consulta fora da URL do servidor; Kanera anexa o próprio tópico.
4. Se o tópico exigir autenticação, cole um token de acesso em Token do portador. É opcional em servidores abertos e obrigatório em servidores protegidos.
5. Clique Salvare, em seguida, ligue Habilitado.
6. Escolha quais tipos de notificação este canal deve entregar.
7. Clique Teste e confirme que a mensagem chega.
8. Assine o mesmo tópico no aplicativo ntfy ou na interface da web, caso ainda não o tenha feito.

Cada notificação chega como uma mensagem simples com um título e, ao tocar nela, o cartão é aberto no Kanera.

Configurar o Gotify

1. Abra sua IU da web Gotify e crie um aplicação — por exemplo, "Kanera".
2. Copie o token do aplicativo gerado pelo Gotify. Os tokens de aplicativo começam com A. Não use um token de cliente.
3. Em Kanera, insira o URL do servidor, como https://gotify.example.come cole o token em Token do aplicativo.
4. Clique Salvare, em seguida, ligue Habilitado.
5. Escolha quais tipos de notificação este canal deve entregar.
6. Clique Teste e confirme se a mensagem aparece no Gotify.

As mensagens aparecem no Gotify no aplicativo que você criou, com o título da notificação, um resumo legível e um link que abre o cartão. Eles são enviados com prioridade normal, portanto, as configurações por aplicativo do Gotify decidem o quão insistente é o alerta.

O token do aplicativo é armazenado criptografado e nunca mais é exibido; o campo mostra Salvo — deixe em branco para manter. Usar Remover token para limpá-lo ou cole um novo token e salve para substituí-lo.

Configure um webhook pessoal

1. Prepare um endpoint HTTPS que aceite POST solicitações com um corpo JSON e retorna um status 2xx rapidamente.
2. Em Kanera, insira o URL do terminal e clique Salvar.
3. Kanera gera um segredo de assinatura e o mostra uma vez. Copie agora - não é mostrado novamente.
4. Armazene o segredo em seu receptor e verifique cada solicitação antes de confiar nele.
5. Ligar Habilitadoe escolha quais tipos de notificação esse canal deve entregar.
6. Clique Teste e confirme se seu endpoint recebeu e verificou a solicitação.

Usar Girar segredo para emitir um novo segredo. O segredo antigo para de funcionar imediatamente, então atualize seu receptor na mesma janela de manutenção.

Solicitar cabeçalhos

Cabeçalho	Significado
Content-Type	Sempre application/json.
User-Agent	Kanera-Personal-Notifications/1.0.
X-Kanera-Event-Id	ID exclusivo para esta entrega. Partidas id no corpo.
X-Kanera-Timestamp	Carimbo de data/hora Unix em segundos.
X-Kanera-Signature	sha256= mais um HMAC-SHA256 de ${timestamp}.${rawBody} usando seu segredo de assinatura.

Carga útil

{
  "id": "0199c3ab-6f5e-7d21-9b0c-8b31a7e40f2d",
  "type": "notification",
  "occurredAt": "2026-07-30T09:14:22.481Z",
  "notification": {
    "kind": "comment_mentioned",
    "reason": "mentioned",
    "title": "Mentioned in a comment",
    "body": "Amelia mentioned you in Website Redesign / Prepare kickoff agenda: can you review the copy?",
    "url": "https://kanera.example.com/b/48a52a55-763e-4c64-8a76-51ac56247f5c/c/70c39cef-1aec-44e6-a8f5-f36f765a818d",
    "tag": "card:70c39cef-1aec-44e6-a8f5-f36f765a818d:mentioned"
  }
}

Campo	Significado
id	ID de entrega, também enviado como X-Kanera-Event-Id. Use-o para tornar seu receptor idempotente.
type	Sempre notification para entregas de canais pessoais.
occurredAt	Carimbo de data/hora ISO 8601 para quando a notificação foi colocada na fila.
notification.kind	Tipo de notificação, como card_assigned, card_comment_added, comment_mentioned, card_due_date_changed, card_overdue, card_reminder, ou test.
notification.reason	Por que você foi notificado: assigned, comment, mentioned, dueDateChanged, overdue, reminder, ou test.
notification.title	Título curto.
notification.body	Resumo legível por humanos, incluindo ator, tabuleiro e cartão.
notification.url	Link direto para o cartão, quando a notificação aponta para um.
notification.tag	Chave de agrupamento para recolher notificações repetidas sobre o mesmo cartão.

Verifique a assinatura

import crypto from "node:crypto";
import express from "express";

const app = express();

app.post("/kanera/notifications", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.header("X-Kanera-Timestamp") ?? "";
  const signature = req.header("X-Kanera-Signature") ?? "";
  const expected = "sha256=" + crypto
    .createHmac("sha256", process.env.KANERA_NOTIFICATION_SECRET!)
    .update(`${timestamp}.${req.body.toString("utf8")}`)
    .digest("hex");

  const ok = signature.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  if (!ok) return res.status(401).send("invalid signature");

  const event = JSON.parse(req.body.toString("utf8"));
  // Handle event.notification.reason, .title, .body, and .url.
  res.sendStatus(204);
});

Sempre verifique o corpo da solicitação bruta. Se sua estrutura analisar JSON antes da verificação, a verificação poderá falhar ou tornar-se não confiável. Rejeitar solicitações cujos X-Kanera-Timestamp está longe do seu próprio relógio e trate um repetido X-Kanera-Event-Id como uma duplicata.

Quais notificações cada canal pode enviar

Os canais pessoais carregam os mesmos cinco tipos de notificação que email e push:

Tipo	Enviado quando
Cartão atribuído	Você está atribuído a um cartão.
Comentário do cartão adicionado	Alguém comenta um cartão atribuído a você.
Marcado em um comentário	Alguém menciona você em um comentário.
Data de vencimento do cartão alterada	A data de vencimento muda em um cartão atribuído a você.
Cartão vencido	Um cartão atribuído ou um item da lista de verificação atribuído está vencido.
Lembretes do seu cartão	Um lembrete que você definiu em um cartão vence.

Cada canal tem seu próprio conjunto de alternâncias de tipo, portanto, um canal pode ser muito mais silencioso que o e-mail. Uma configuração comum é e-mail para tudo, ntfy apenas para menções e trabalhos atrasados, e um webhook para tarefas que alimentam um script pessoal.

A atividade do observador passivo aparece na gaveta do aplicativo e o resumo diário é enviado apenas por e-mail. Nenhum dos dois é entregue em canais pessoais.

Destinos permitidos e segurança

Kanera verifica cada destino quando você o salva e novamente antes de cada notificação ser enviada.

Por padrão:

• Os destinos devem usar HTTPS público.
• O URL não pode conter nome de usuário e senha (https://user:pass@host) ou um #fragment.
• Uma URL de servidor ntfy ou Gotify não pode conter uma string de consulta. Digite apenas o endereço do servidor.
• Endereços numa rede privada ou interna são recusados.
• Um destino que redireciona para outro lugar é tratado como uma falha e Kanera não espera mais do que 10 segundos por uma resposta.

Algumas instalações do Kanera permitem receptores em uma rede interna, que é o que um servidor ntfy ou Gotify rodando em casa ou em uma LAN corporativa geralmente precisa. Alguns endereços permanecem bloqueados de qualquer maneira, incluindo aqueles que os provedores de nuvem reservam para sua própria infraestrutura. A página de configurações de notificação informa qual das duas políticas se aplica a você; se você precisar da política de rede interna, pergunte a quem administra seu Kanera.

Seus tokens e segredos de assinatura são armazenados criptografados e nunca mais serão exibidos depois que você os salvar. Se uma entrega falhar, Kanera registra que houve falha sem registrar seu destino ou credenciais.

O que esperar da entrega

As notificações chegam em cerca de meio minuto, em vez de instantaneamente. Kanera os envia em segundo plano, então nada do que você faz no aplicativo aguarda a resposta do servidor ntfy ou do webhook.

Se o seu destino ficar inacessível por um breve período, Kanera tenta mais algumas vezes antes de desistir da notificação. Nada se acumula por dias também. Se você desativar um canal, limpar seus detalhes ou se a organização adotar um plano sem canais pessoais, tudo o que ainda estiver em espera será descartado, em vez de chegar horas depois, fora do contexto.

Teste envia imediatamente e funciona mesmo antes de você ativar o canal, para que você possa confirmar a conexão primeiro.

Solução de problemas

Problema	Verifique
Kanera recusa o URL ao salvar.	Usar https://, remova qualquer nome de usuário, senha ou #fragmente remova a string de consulta de um URL de servidor ntfy ou Gotify. Um endereço privado ou interno só é aceite onde a sua instalação o permitir.
A seção inteira diz que não está disponível no seu plano.	Canais pessoais precisam do Pro ou de uma avaliação Pro. E-mail, push do navegador e gaveta do aplicativo não são afetados.
Cada canal se desligou sozinho.	Verifique se a organização mudou para Gratuito. Um downgrade desativa a entrega de ntfy, Gotify e webhook e mantém as conexões salvas; a atualização os liga novamente.
O Habilitado alternar está esmaecido.	O canal não está totalmente configurado. ntfy precisa de uma URL de servidor e um tópico, Gotify precisa de uma URL de servidor e um token de aplicativo, e um webhook precisa de uma URL com um segredo gerado.
O teste diz que o canal não está totalmente configurado.	Salve os campos de conexão primeiro e depois teste.
O teste falha com um status HTTP.	O destino rejeitou a solicitação. Para ntfy, verifique o tópico e qualquer token necessário. Para Gotify, confirme que você usou um token de aplicativo, não um token de cliente. Para um webhook, retorne um status 2xx.
O teste atinge o tempo limite ou relata uma falha na rede.	Kanera não conseguiu alcançar o host em 10 segundos. Confirme se o host está acessível a partir do servidor Kanera e lembre-se de que os redirecionamentos não são seguidos.
Nada chega mesmo que o teste tenha funcionado.	Verifique as opções de tipo de notificação nesse canal e, em seguida, verifique se um regra do espaço de trabalho pausa ou restringe a entrega desse espaço de trabalho.
O receptor do webhook rejeita assinaturas.	Verifique o corpo bruto, não um objeto re-serializado, e confirme se você está usando o segredo atual se você o girou recentemente.
As notificações foram interrompidas após a rotação de um segredo.	Atualize o receptor. O segredo anterior para de funcionar imediatamente.

O que ler a seguir

• Configuração
• Regras do espaço de trabalho
• Destinos de bate-papo
• Notificações