Alertes

Les alertes vous permettent de réagir automatiquement aux signaux de sécurité de vos transferts, sans surveiller un tableau de bord en continu. Une règle d'alerte associe une condition (par exemple un pic de téléchargements ou une série d'échecs de mot de passe) à une action de notification (e-mail, Slack, Discord ou webhook). Les règles vivent dans votre espace de travail, restent actives en arrière-plan et se déclenchent dès que la condition est remplie. Cette page décrit comment créer, lister et gérer ces règles via la ressource /v1/alerts, puis comment couvrir les signaux de facturation et de livraison de webhooks qui passent par les évènements webhook.

Portée et scopes

Toutes les opérations sur les alertes utilisent l'authentification standard Authorization: Bearer <clé> sur la base https://api.coffrify.com/v1. La lecture des règles exige le scope alerts:read ; la création, la modification et la suppression exigent alerts:manage. Comme partout dans l'API, une clé ne peut faire que ce que ses scopes autorisent : si la clé ne porte pas le bon scope, la requête échoue avec scope_missing.

Sur quels signaux alerter

Une règle se définit par un condition_type et un action_type. Le condition_type choisit le signal surveillé, et le champ libre condition_value porte le seuil associé. Cinq signaux sont disponibles. Le pic de téléchargements (download_count pour un volume total, download_rate pour un rythme) couvre l'exfiltration ou la fuite d'un lien ; failed_password repère les tentatives répétées sur un transfert protégé ; geo_unexpected signale un accès depuis un pays inattendu ; expiration_soon vous prévient avant qu'un transfert n'expire.

Où router les notifications

Le action_type indique la destination, et action_value porte l'adresse cible. Quatre canaux sont disponibles : email (clé to), slack et discord (clé channel, un identifiant ou une URL de salon), et webhook (clé url, une URL HTTPS qui reçoit la charge utile au déclenchement).

Créer une règle

Pour créer une règle, envoyez un POST /v1/alerts avec au minimum un name et un condition_type valide. L'action_type vaut email par défaut. Vous pouvez restreindre la règle à un transfert précis avec transfer_id, ou la laisser à null pour qu'elle s'applique à l'ensemble de l'espace de travail. La création renvoie un statut 201 avec la règle complète, identifiant compris. Comme toute écriture, l'endpoint accepte l'en-tête Idempotency-Key (8 à 255 caractères) pour rejouer sans risque la même création.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
// Alerte sur un pic de téléchargements, notifiée sur Slack
const rule = await coffrify.alerts.create({
  name: 'Pic de téléchargements',
  transfer_id: null,
  condition_type: 'download_count',
  condition_value: { threshold: 100 },
  action_type: 'slack',
  action_value: { channel: '#securite' },
  is_active: true,
});
 
console.log(rule.id);

Voici quelques recettes courantes. Pour être prévenu avant qu'un transfert sensible n'expire, par e-mail, six heures à l'avance : condition_type expiration_soon, condition_value { "hours": 6 }, action_type email, action_value { "to": "secu@exemple.fr" }. Pour détecter des tentatives de mot de passe répétées et pousser l'alerte vers votre propre service, utilisez failed_password avec condition_value { "threshold": 5 } et action_type webhook (action_value { "url": "https://exemple.fr/hooks/coffrify" }).

Lister les règles

Un GET /v1/alerts renvoie toutes les règles de l'espace de travail, les plus récentes d'abord, sous la forme d'une liste { "object": "list", "data": [...] }. Chaque entrée expose son condition_type, son action_type, l'indicateur is_active et le champ last_triggered_at, qui vaut null tant que la règle ne s'est jamais déclenchée. C'est le moyen le plus simple de savoir quelles règles ont récemment réagi.

const { data } = await coffrify.alerts.list();
 
for (const rule of data) {
  console.log(rule.name, rule.is_active, rule.last_triggered_at);
}

Activer, suspendre ou ajuster une règle

Le PATCH /v1/alerts/{id} met à jour une règle existante. Vous pouvez renommer (name), suspendre ou réactiver (is_active), ou ajuster les seuils et destinations en repassant un condition_value ou un action_value complet. Au moins un champ modifiable doit être fourni, sinon la requête renvoie validation_error. Un identifiant inconnu renvoie not_found. Suspendre une règle plutôt que la supprimer est utile pour faire taire temporairement une alerte trop bavarde, sans perdre sa configuration.

// Suspendre une règle
await coffrify.alerts.update('alr_123', { is_active: false });
 
// Relever le seuil sans la recréer
await coffrify.alerts.update('alr_123', {
  condition_value: { threshold: 250 },
});

Supprimer une règle

Le DELETE /v1/alerts/{id} retire définitivement une règle et renvoie { "id": "…", "object": "alert_rule", "deleted": true }. Si la règle n'existe pas (ou appartient à un autre espace de travail), la réponse est not_found. Pour ne couper l'alerte que momentanément, préférez is_active: false via un PATCH.

$ curl -X DELETE https://api.coffrify.com/v1/alerts/alr_123 \
    -H "Authorization: Bearer $COFFRIFY_API_KEY"
{ "id": "alr_123", "object": "alert_rule", "deleted": true }

Dépassement de quota et échec de webhook

Les règles /v1/alerts couvrent les signaux propres aux transferts. Deux autres signaux importants, le dépassement de quota et l'échec de livraison d'un webhook, ne sont pas des condition_type mais des évènements webhook que vous recevez en temps réel. Abonnez un endpoint à ces évènements pour les router comme vous le souhaitez. Pour les quotas, workspace.usage_limit_warning se déclenche à 80 % d'une limite de plan (stockage, transferts par mois, etc.) et workspace.usage_limit_reached à 100 %, moment où les nouveaux dépôts sont refusés. Pour la fiabilité de vos propres webhooks, webhook.delivery_failed_final signale qu'une livraison a épuisé son budget de nouvelles tentatives et a été abandonnée.

• workspace.usage_limit_warning : 80 % d'une limite de plan atteinte.
• workspace.usage_limit_reached : 100 % atteint, les nouveaux dépôts sont refusés.
• webhook.delivery_failed_final : une livraison de webhook a épuisé ses tentatives et a été abandonnée.

Erreurs courantes

Les erreurs suivent le format standard { "error": { "code", "message", "request_id" } }. Conservez le request_id pour le support. Les cas les plus fréquents sur les alertes : scope_missing quand la clé ne porte pas alerts:read ou alerts:manage ; validation_error quand condition_type ou action_type n'est pas l'une des valeurs autorisées, ou quand un PATCH ne contient aucun champ modifiable ; not_found sur un identifiant de règle inconnu ; et rate_limited (statut 429, avec en-tête Retry-After) si vous dépassez le quota de requêtes de l'espace de travail.