API d'Alertes Récurrentes : 4 Règles Cron pour Dompter Fuseaux et Webhooks

Dans l'écosystème du développement web, automatiser l'envoi de notifications programmées paraît simple en surface. Pourtant, quiconque a déjà implémenté un système d'alertes récurrentes distribué sait que la gestion du temps est un défi technique redoutable. Entre le passage à l'heure d'été, les mois de 28 ou 31 jours et les fuseaux horaires des utilisateurs, une tâche planifiée peut rapidement se transformer en casse-tête de production.

Pour construire une API d'alertes robuste capable de déclencher des webhooks fiables, voici quatre règles architecturales essentielles autour de Cron et des fuseaux horaires.

1. Stocker le fuseau IANA, jamais un simple décalage UTC

L'erreur classique consiste à convertir l'heure locale souhaitée par l'utilisateur directement en UTC au moment de l'enregistrement, ou à enregistrer un décalage fixe comme UTC+1. Cette approche échoue systématiquement lors des changements d'heure (DST).

Pour garantir qu'une alerte programmée à 9h00 arrive toujours à 9h00 pour un utilisateur à Paris, stockez systématiquement l'identifiant de fuseau horaire de la base IANA (ex. Europe/Paris ou America/New_York). Votre planificateur d'alertes doit recalculer la prochaine occurrence en UTC dynamiquement en tenant compte des transitions d'heure saisonnières.

2. Les alertes hebdomadaires : maîtriser le découpage des jours

Les alertes hebdomadaires (par exemple : « Tous les lundis à 08h00 ») semblent linéaires, mais leur conversion en heure machine dépend du fuseau cible. Le lundi matin en Asie correspond encore au dimanche soir en Amérique du Nord.

• Évitez d'exécuter un cron unique qui balaye toute la base chaque minute.
• Calculez à l'avance des fenêtres d'exécution (buckets horaires) en UTC pour chaque souscription.
• Utilisez des index composites sur votre base de données (next_run_at, status) pour interroger uniquement les alertes dues dans la tranche courante.

3. Les alertes mensuelles : anticiper le piège des fins de mois

Que se passe-t-il si un utilisateur demande une alerte récurrente le 31 du mois ? En février, avril, juin, septembre et novembre, une règle cron basique comme 0 9 31 * * sera tout simplement ignorée.

Pour une API d'alertes flexible, deux stratégies existent :

• Le report automatique : si le mois ne compte pas 31 jours, l'événement est avancé au dernier jour du mois (le 28 ou 29 février).
• Les motifs relatifs : implémentez le support pour des expressions telles que « le dernier vendredi du mois » ou « le premier jour ouvré », souvent beaucoup plus adaptées aux besoins métier financiers ou administratifs.

4. Découpler l'évaluation Cron de l'émission des Webhooks

Un planificateur Cron ne doit jamais effectuer directement d'appels réseau HTTP. Les serveurs récepteurs de webhooks peuvent être lents, hors ligne ou renvoyer des erreurs 500. Si votre boucle d'évaluation bloque sur une requête, toute la file d'attente prend du retard.

L'architecture idéale sépare strictement les responsabilités :

• Le Scheduler : vérifie les alertes dues et pousse un événement léger dans une file de messages (RabbitMQ, Redis Streams, SQS).
• Les Workers : consomment ces messages, construisent le payload et envoient le webhook avec un mécanisme de retry exponentiel.
• L'idempotence : générez une clé d'idempotence unique (ex. alert_id:timestamp_occurrence) pour éviter les doublons lors des réémissions.

En découplant la logique d'horloge de l'exécution réseau et en respectant les spécificités des fuseaux IANA, votre API d'alertes récurrentes restera prévisible, tolérante aux pannes et prête à monter en charge.