# Canais de notificação

Para conectar o app passo a passo, consulte [Conecte o aplicativo](connect-app.md) .

## Configurar no console

1. Abra **Notificações** e escolha Bark, Pushover, Webhook ou Mailwake App.
2. Preencha os campos do canal selecionado abaixo. Para o aplicativo Mailwake, primeiro [emparelhar o telefone](connect-app.md) e, em seguida, escolha o telefone receptor.
3. Escolha a visualização, o idioma de notificação e a contagem de novas tentativas. Uma contagem de novas tentativas de 0 faz uma tentativa.
4. Salve e envie explicitamente uma notificação de teste. Verifique o receptor do telefone ou webhook e o resultado da entrega.

As configurações se aplicam a todas as caixas de correio. A alteração das configurações preserva o trabalho na fila de acordo com o plano de entrega existente; verifique o comportamento futuro com uma nova mensagem.

## Configuração do canal

Configure o canal global através de `/api/v1/settings/delivery` , enviando seu `revision` atual . Canal, visualização, contagem de novas tentativas e idioma de notificação se aplicam a todas as caixas de correio. Todas as credenciais são criptografadas e somente gravação; as credenciais omitidas são mantidas se o destino não mudar. Ao alterar um endereço Bark salvo, informe novamente a chave do dispositivo.

| Canal      | Parâmetros                                                                                                                                      | Credenciais                                                                      |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `bark`     | `bark.endpoint`, padrão `https://api.day.app`                                                                                                   | `bark.key`                                                                       |
| `pushover` | nenhum                                                                                                                                          | `pushover.token`, `pushover.user`                                                |
| `webhook`  | HTTPS, consulta permitida                                                                                                                       | `webhook.url` e `webhook.secret` (pelo menos 32 caracteres sem espaço em branco) |
| `native`   | Serviço oficial de entrega push de produção por padrão; substituir por `MAILWAKE_RELAY_URL` ; emparelhar telefones na autorização do aplicativo | Identidade de posto criptografada gerada localmente                              |

URLs de webhook são somente gravação porque caminhos e consultas podem conter credenciais de roteamento. `preview` aceita `off` ou `subject`; `retry_count` aceita 0–9 e o padrão é 0; `language` aceita [nove códigos de catálogo e seus apelidos regionais](api.md#idiomas-e-códigos-de-erro) e o padrão é `en` . Bark e Pushover mostram apenas o assunto com `subject` ; O Webhook retém remetente e assunto estruturados, enquanto seu `message` também contém apenas o assunto. `off` (e um assunto vazio) usa a mensagem localizada “Novo e-mail”. Os títulos permanecem `{display name} · {folder}`; Bark agrupa pelo mesmo título truncado. O texto da notificação de teste permanece inalterado. A entrada da API `sender_subject` retorna 400 `config_preview_invalid` . Para canais de terceiros, a mudança de `subject` para `off` remove atomicamente o remetente e o assunto de todos os registros pendentes e com falha; enfileiramentos posteriores também seguem a política de privacidade salva. O push nativo sempre registra o remetente e o assunto, preservando a preferência de visualização de terceiros.

A retenção do histórico do Bark segue a configuração de histórico de salvamento do aplicativo Bark para notificações de e-mail e de teste.

### Carga útil do webhook

O posto envia um `POST` com um corpo JSON e nunca segue redirecionamentos:

```json
{
  "version": 1,
  "id": "3f9c…",
  "test": false,
  "mailbox_id": "mbx_example",
  "account": "Work mailbox",
  "folder": "Clients",
  "sender": "anna@example.org",
  "subject": "Re: Q4 proposal",
  "received_at": "2026-09-28T10:32:00Z",
  "title": "Work mailbox · Clients",
  "message": "Re: Q4 proposal"
}
```

`mailbox_id` é o ID da caixa de correio estável; `account` é seu nome de exibição no momento do enfileiramento. As notificações comuns Bark, Pushover e Webhook usam o título `{display name} · {folder}` em todos os idiomas compatíveis. Renomear ou excluir uma caixa de correio preserva os metadados de identidade de tarefas já enfileiradas. As notificações de teste usam texto separado e omitem campos de caixa de correio.

`sender` e `subject` aparecem apenas com a visualização `subject`. `title` e `message` estão localizados e prontos para serem encaminhados para ntfy, Gotify e serviços semelhantes. O nome de exibição e a pasta são enviados mesmo com a visualização desativada; escolha um rótulo adequado para compartilhar com seu provedor de notificação.

| Cabeçalho              | Significado                                                                          |
| ---------------------- | ------------------------------------------------------------------------------------ |
| `X-Mailwake-Event`     | ID do Evento, igual a `id` ; inalterado nas novas tentativas, use-o para desduplicar |
| `X-Mailwake-Timestamp` | Tempo de envio em segundos Unix                                                      |
| `X-Mailwake-Signature` | `sha256=` seguido pelo hexadecimal `HMAC-SHA256(secret, "<timestamp>.<raw body>")`   |

Verifique a assinatura com o mesmo segredo usando uma comparação de tempo constante e rejeite carimbos de data/hora com mais de cinco minutos de distância:

```python
import hashlib, hmac, time

def verify(secret: bytes, timestamp: str, body: bytes, signature: str) -> bool:
    expected = "sha256=" + hmac.new(secret, timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(timestamp)) <= 300 and hmac.compare_digest(expected, signature)
```

Qualquer resposta 2xx conta como aceita. 429 e 5xx seguem a configuração de nova tentativa; outros status encerram a tentativa e registram uma falha.

Salvar configurações de notificação valida campos, endereços, estado de emparelhamento e revisão sem enviar um teste. Use o botão de teste explícito após salvar. Os testes nativos usam o endpoint de teste gratuito fixo do serviço de envio de notificações e compartilham a cota de teste do aplicativo; notificações comuns por e-mail exigem direitos de push nativo.