# Canaux de notification

Pour une connexion téléphonique étape par étape, voir [Connectez l'application](connect-app.md) .

## Configurer dans la console

1. Ouvrez **Notifications** et choisissez l'application Bark, Pushover, Webhook ou Mailwake.
2. Remplissez les champs de la chaîne sélectionnée ci-dessous. Pour l'application Mailwake, commencez par [jumeler le téléphone](connect-app.md), puis choisissez le téléphone de réception.
3. Choisissez l'aperçu, la langue de notification et le nombre de tentatives. Un nombre de tentatives de 0 effectue une tentative.
4. Enregistrez, puis envoyez explicitement une notification de test. Vérifiez le téléphone ou le récepteur webhook et le résultat de la livraison.

Les paramètres s'appliquent à toutes les boîtes aux lettres. La modification des paramètres préserve le travail en file d'attente selon son plan de livraison existant ; vérifier le comportement futur avec un nouveau message.

## Configuration des canaux

Configurez le canal global via `/api/v1/settings/delivery` , en envoyant son `revision` actuel. Le canal, l'aperçu, le nombre de tentatives et la langue de notification s'appliquent à toutes les boîtes aux lettres. Toutes les informations d'identification sont chiffrées et en écriture seule ; les identifiants omis sont conservés si la destination reste identique. Modifier une adresse Bark enregistrée exige de saisir à nouveau la clé de l’appareil.

| Canal      | Paramètres                                                                                                                                                      | Informations d'identification                                                     |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `bark`     | `bark.endpoint` , `https://api.day.app` par défaut                                                                                                              | `bark.key`                                                                        |
| `pushover` | aucun                                                                                                                                                           | `pushover.token` , `pushover.user`                                                |
| `webhook`  | HTTPS, requête autorisée                                                                                                                                        | `webhook.url` et `webhook.secret` (au moins 32 caractères autres que des espaces) |
| `native`   | Service officiel de livraison push de production par défaut ; remplacer par `MAILWAKE_RELAY_URL` ; Associer des téléphones dans l'autorisation de l'application | Identité d'avant-poste générée localement et chiffrée                             |

Les URL de webhook sont en écriture seule, car les chemins et les requêtes peuvent contenir des informations d'identification de routage. `preview` accepte `off` ou `subject` ; `retry_count` accepte 0 à 9 et la valeur par défaut est 0 ; `language` accepte le [neuf codes de catalogue et leurs alias régionaux](api.md#langues-et-codes-derreur) et est par défaut `en` . Bark et Pushover affichent uniquement le sujet avec `subject` ; Webhook conserve l'expéditeur et le sujet structurés, tandis que son `message` ne contient également que le sujet. `off` (et un objet vide) utilise le message localisé « Nouveau courrier ». Les titres restent `{display name} · {folder}` ; Bark regroupe par ce même titre tronqué. Le texte de la notification de test est inchangé. L'entrée API `sender_subject` renvoie 400 `config_preview_invalid` . Pour les canaux tiers, le passage de `subject` à `off` supprime atomiquement l'expéditeur et le sujet de tous les enregistrements en attente et en échec ; les mises en file d'attente ultérieures suivent également la politique de confidentialité enregistrée. Le push natif enregistre toujours l'expéditeur et le sujet tout en préservant la préférence d'aperçu tiers.

La conservation de l'historique Bark suit le paramètre d'historique de sauvegarde de l'application Bark pour les notifications par courrier électronique et de test.

### Charge utile du webhook

L'avant-poste envoie un `POST` avec un corps JSON et ne suit jamais les redirections :

```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` est l’ID de boîte aux lettres stable ; `account` est son nom d'affichage au moment de la mise en file d'attente. Les notifications ordinaires Bark, Pushover et Webhook utilisent le titre `{display name} · {folder}` dans toutes les langues prises en charge. Renommer ou supprimer une boîte aux lettres préserve les métadonnées d'identité des tâches déjà mises en file d'attente. Les notifications de test utilisent un texte séparé et omettent les champs de boîte aux lettres.

`sender` et `subject` apparaissent uniquement avec l'aperçu `subject`. `title` et `message` sont localisés et prêts à être transmis à ntfy, Gotify et à des services similaires. Le nom d'affichage et le dossier sont envoyés même avec l'aperçu désactivé ; choisissez une étiquette adaptée au partage avec votre fournisseur de notifications.

| En-tête                | Signification                                                                                        |
| ---------------------- | ---------------------------------------------------------------------------------------------------- |
| `X-Mailwake-Event`     | ID d'événement, égal à `id` ; inchangé au fil des tentatives, utilisez-le pour dédupliquer           |
| `X-Mailwake-Timestamp` | Heure d'envoi en secondes Unix                                                                       |
| `X-Mailwake-Signature` | `sha256=` suivi de la représentation hexadécimale de `HMAC-SHA256(secret, "<timestamp>.<raw body>")` |

Vérifiez la signature avec le même secret à l'aide d'une comparaison à temps constant et rejetez les horodatages à plus de cinq minutes :

```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)
```

Toute réponse 2xx compte comme acceptée. 429 et 5xx suivent le paramètre de nouvelle tentative ; d'autres statuts mettent fin à la tentative et enregistrent un échec.

L'enregistrement des paramètres de notification valide les champs, les adresses, l'état d'appairage et la révision sans envoyer de test. Utilisez le bouton de test explicite après la sauvegarde. Les tests natifs utilisent le point de terminaison de test gratuit fixe du service de transmission des notifications et partagent le quota de test de l'application ; les notifications par courrier électronique ordinaires nécessitent le droit Native Push.