Notifications

Les notifications Coffrify alertent votre équipe quand quelque chose se passe dans votre espace de travail : un fichier téléchargé, un quota proche de la limite, un transfert ouvert pour la première fois. L'API /v1/notifications vous laisse lire et modifier les préférences de notification du propriétaire de l'espace, router ces alertes vers Slack, Discord ou Microsoft Teams, lister le flux affiché dans le tableau de bord, marquer des notifications comme lues et tester une intégration avant de compter dessus. Toutes les écritures se font avec une clé API Bearer, sur la base https://api.coffrify.com/v1.

Portées requises

Deux portées gouvernent cette ressource. La lecture du flux et le marquage comme lu demandent notifications:read. Modifier les préférences (e-mail, fréquence du récapitulatif, URLs de webhook entrant) et tester une intégration demandent notifications:manage. Une clé qui ne porte pas la bonne portée reçoit une erreur scope_missing. Les portées d'une clé délimitent strictement ce qu'elle peut faire : créez une clé restreinte (cof_rk_) dédiée aux notifications si vous automatisez ce périmètre depuis un service externe.

Lire et modifier les préférences

GET /v1/notifications renvoie les préférences de notification du propriétaire de l'espace de travail dans un objet prefs. Vous y trouvez les bascules e-mail (email_on_download, email_on_limit), la fréquence du récapitulatif (digest_frequency) et les trois URLs de webhook entrant vers vos canaux d'équipe (slack_webhook_url, discord_webhook_url, teams_webhook_url).

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const { prefs } = await coffrify.notifications.get();
console.log(prefs.digest_frequency);   // "daily"
console.log(prefs.slack_webhook_url);   // null si non branché

PATCH /v1/notifications met à jour un sous-ensemble de ces champs. N'envoyez que ce que vous changez : seuls les champs reconnus sont appliqués, le reste est ignoré. Le champ digest_frequency n'accepte que none, daily, weekly ou monthly ; toute autre valeur renvoie une erreur validation_error. Brancher un canal revient simplement à poser son URL de webhook entrant ; le détacher revient à la mettre à null. Pensez à fournir un en-tête Idempotency-Key (8 à 255 caractères) sur cet appel d'écriture pour qu'un rejeu réseau ne s'applique pas deux fois.

const { prefs } = await coffrify.notifications.update({
  digest_frequency: 'weekly',
  email_on_download: true,
  slack_webhook_url: 'https://hooks.slack.com/services/T000/B000/XXXX',
}, { idempotencyKey: 'prefs-2026-06-10-01' });
 
console.log(prefs.digest_frequency); // "weekly"

Brancher Slack, Discord ou Teams

Chaque canal se branche avec l'URL d'un webhook entrant que vous créez côté Slack, Discord ou Teams. Une fois l'URL posée dans les préférences (slack_webhook_url, discord_webhook_url, teams_webhook_url), Coffrify y publie les notifications de l'espace au fil de l'eau. Coffrify valide le domaine de l'URL pour chaque canal : Slack attend https://hooks.slack.com/..., Discord https://discord.com/api/webhooks/..., Teams https://*.webhook.office.com/... ou https://*.logic.azure.com/.... Une URL d'un autre domaine est refusée par une erreur validation_error.

Tester une intégration

Avant de compter sur un canal, envoyez-lui un message de test avec POST /v1/notifications/test/{canal}, où {canal} vaut slack, discord ou teams. Le corps prend l'url du webhook à tester et un message facultatif (à défaut, un message par défaut est envoyé). La réponse vous dit si le canal a bien reçu le ping : ok (booléen), status (code HTTP renvoyé par le canal), duration_ms, un body_preview de la réponse et un éventuel error. C'est l'outil idéal pour diagnostiquer une URL périmée ou un canal mal configuré sans attendre une vraie notification.

const res = await coffrify.notifications.test('slack', {
  url: 'https://hooks.slack.com/services/T000/B000/XXXX',
  message: 'Test depuis Coffrify',
});
 
if (res.ok) console.log('Slack joignable en', res.duration_ms, 'ms');
else console.error('Echec', res.status, res.error);

Lister le flux et marquer comme lu

GET /v1/notifications/feed renvoie le flux in-app, celui qui alimente la cloche du tableau de bord. Le paramètre limit accepte une valeur entre 1 et 50 (5 par défaut). Chaque entrée porte id, title, un body éventuel, created_at, read_at (ou null si non lue), un lien href et un libellé d'action cta_label. Pour marquer une ou plusieurs entrées comme lues, envoyez leurs identifiants à POST /v1/notifications/mark-read dans un tableau ids ; la réponse marked compte combien ont été effectivement marquées (les entrées déjà lues ne sont pas recomptées). Pour vider la boîte, POST /v1/notifications/clear archive toutes les notifications non archivées et renvoie cleared ainsi que archived_until (la date jusqu'à laquelle l'archive est conservée, 30 jours).

const { data } = await coffrify.notifications.feed({ limit: 20 });
 
const unread = data.filter((n) => n.read_at === null).map((n) => n.id);
if (unread.length) {
  const { marked } = await coffrify.notifications.markRead({ ids: unread });
  console.log(marked, 'notifications marquees comme lues');
}

Notifications ou webhooks ?

Les deux mécanismes partent du même évènement, mais ne servent pas le même public. Une notification est un message lisible destiné à un humain : elle arrive dans un canal Slack, sur la cloche du tableau de bord ou dans un e-mail récapitulatif, et son but est d'informer une personne. Un webhook est un évènement machine : Coffrify livre à votre serveur une charge utile structurée et signée pour que votre code réagisse (lancer un traitement, mettre à jour une base, relayer vers un autre service). Choisissez les notifications pour tenir votre équipe au courant ; choisissez les webhooks pour automatiser une réaction fiable et vérifiable.