Webhooks Nextcloud : connecter des automatisations en 2026

Votre équipe doit-elle prévenir un outil métier dès qu'un formulaire est envoyé, sans interroger Nextcloud toutes les minutes ? En 2026, les webhooks Nextcloud permettent à l'instance d'envoyer un événement vers une URL HTTPS lorsqu'une action compatible se produit. Le système externe reçoit alors un corps JSON qu'il peut contrôler, enregistrer et transmettre à son propre traitement.

Ce guide explique ce mécanisme sortant, le choix d'un événement, l'enregistrement par API REST, les filtres, la protection du point de réception et la recette avant production. Il se concentre sur les notifications techniques, pas sur la conception complète d'un processus métier. Pour revoir d'abord les fonctions, applications et modes d'hébergement, commencez par le guide Nextcloud.

Qu'est-ce qu'un webhook Nextcloud, et quand le choisir ?

Un webhook relie un événement produit dans Nextcloud à une requête HTTP sortante. L'application webhook_listeners, installée par défaut depuis Nextcloud 28 selon le manuel d'administration, écoute les classes d'événements déclarées compatibles. Lorsqu'une correspondance existe, elle prépare un message JSON puis ajoute l'appel à la file des tâches d'arrière-plan.

Le sens du flux permet de distinguer trois outils souvent confondus. Un webhook part de Nextcloud vers un récepteur externe. Une API permet au contraire à un programme de demander une action à Nextcloud, par exemple déposer un fichier ou créer un partage. Le guide de l'API Nextcloud détaille WebDAV et OCS pour ce second cas.

Nextcloud Flow couvre un périmètre plus large : règles internes, données structurées et orchestration de plusieurs étapes. Un webhook peut devenir le déclencheur d'un tel processus, mais il ne gère pas à lui seul les validations, les délais et les reprises. Le guide Nextcloud Flow et automatisation aide à choisir entre une règle locale, une API et un moteur de workflow.

Besoin	Mécanisme adapté	Sens principal
Prévenir un service après un événement	Webhook	Nextcloud vers service externe
Lire ou modifier fichiers, partages ou comptes	API WebDAV ou OCS	Service externe vers Nextcloud
Enchaîner plusieurs étapes et décisions	Flow ou orchestrateur	Plusieurs systèmes
Synchroniser une arborescence	Client ou WebDAV	Bidirectionnel selon le client

Quels événements et quelles données peut-on recevoir ?

Tous les événements internes de Nextcloud ne sont pas exposés. La classe doit implémenter l'interface prévue pour les webhooks, et l'application concernée doit publier les événements compatibles. La documentation stable liste notamment des événements pour Forms. D'autres applications peuvent en ajouter, mais leur présence dépend de la version installée.

Pour Forms, l'événement OCA\Forms\Event\NewFormSubmissionEvent signale une nouvelle soumission. Le manuel officiel montre un objet event contenant la classe, les informations du formulaire, la soumission et ses réponses. Le message comporte aussi un objet user, qui peut être nul, ainsi qu'un horodatage Unix dans time. Les réponses peuvent donc contenir des données personnelles ou des informations métier.

Le guide Nextcloud Forms explique comment limiter les questions, les droits et la durée de conservation avant d'automatiser les réponses. Un webhook ne réduit pas la collecte initiale. Il crée au contraire un nouveau destinataire et, souvent, de nouveaux journaux à intégrer dans l'analyse des accès.

N'écrivez pas le traitement en supposant que chaque événement possède les mêmes champs. La forme de event dépend de sa classe. Enregistrez d'abord un exemple réel sur une instance de test, puis validez explicitement les champs obligatoires. Si une propriété manque, placez le message en erreur contrôlée au lieu de poursuivre avec une valeur vide.

Le code stable35 ajoute les appels à une file de tâches. Cette exécution différée protège la requête utilisateur d'un récepteur lent, mais elle signifie aussi que l'appel n'est pas instantané au sens strict. Le délai dépend du traitement des tâches d'arrière-plan de l'instance.

Comment enregistrer un webhook avec l'API REST ?

L'API de l'application expose l'endpoint administrateur /ocs/v2.php/apps/webhook_listeners/api/v1/webhooks. La création demande au minimum la méthode HTTP, l'URL du récepteur et le nom complet de la classe d'événement. Les paramètres facultatifs couvrent le filtre sur les données, le filtre utilisateur, les en-têtes et l'authentification par en-tête.

Préparez un compte administrateur avec un mot de passe d'application distinct. Le guide des mots de passe d'application Nextcloud montre comment créer puis révoquer ce secret. Ne réutilisez ni le mot de passe principal ni l'identifiant du service recevant les événements.

Cet exemple enregistre les nouvelles soumissions Forms et protège le récepteur avec un jeton fictif :

NC_URL="https://cloud.exemple.fr"
NC_ADMIN="admin-automation"
NC_APP_PASSWORD="MOT_DE_PASSE_APPLICATION"

curl --fail-with-body \
  --user "$NC_ADMIN:$NC_APP_PASSWORD" \
  --request POST \
  --header "OCS-APIRequest: true" \
  --header "Content-Type: application/json" \
  --data '{
    "httpMethod": "POST",
    "uri": "https://automation.exemple.fr/hooks/nextcloud",
    "event": "OCA\\Forms\\Event\\NewFormSubmissionEvent",
    "eventFilter": {},
    "userIdFilter": null,
    "headers": {"Content-Type": "application/json"},
    "authMethod": "header",
    "authData": {"Authorization": "Bearer REMPLACER_CE_SECRET"}
  }' \
  "$NC_URL/ocs/v2.php/apps/webhook_listeners/api/v1/webhooks"

Le schéma officiel stable35 définit deux modes d'authentification du webhook : none et header. Le second ajoute au départ les en-têtes placés dans authData. Utilisez HTTPS, un secret propre à cette connexion et une rotation documentée. Ne placez pas le secret dans l'URL, car celle-ci risque d'apparaître dans davantage de journaux.

L'API permet aussi de lister, consulter, modifier et supprimer les inscriptions. La commande suivante fournit un inventaire local utile avant toute intervention :

sudo -u www-data php occ webhook_listeners:list

Le compte système, le chemin de PHP et l'emplacement de occ dépendent de l'installation. Commencez par une commande de lecture. Conservez ensuite l'identifiant renvoyé par l'API, la classe d'événement, le propriétaire métier, l'URL et la date de rotation du secret.

Comment filtrer les appels sans perdre un événement utile ?

Un abonnement sans filtre reçoit chaque occurrence de la classe choisie. C'est acceptable pour une recette courte, mais rarement pour une production partagée. eventFilter applique une requête de style MongoDB aux données sérialisées. Le code stable35 accepte les chemins imbriqués et plusieurs opérateurs, dont l'égalité, $in, $ne, $exists, $and, $or et des comparaisons.

Pour limiter l'exemple Forms à un formulaire précis, un filtre peut viser son identifiant :

{
  "eventFilter": {
    "event.form.id": 42
  }
}

Vérifiez cet identifiant et la structure du message sur l'instance cible. Une erreur de chemin peut empêcher tous les appels attendus. Avant d'activer le filtre, conservez un message de test, ajoutez une soumission qui doit passer et une autre qui doit être refusée, puis contrôlez les deux résultats.

userIdFilter répond à un besoin différent : limiter le déclenchement aux requêtes effectuées par un utilisateur donné. Il n'est pas adapté à tous les événements, car le message peut provenir d'un contexte sans utilisateur connecté. Pour une soumission publique, filtrez plutôt sur les données de l'événement lorsque l'application les fournit.

Comment construire un récepteur fiable et sécurisé ?

Le point de réception doit répondre vite. Vérifiez l'en-tête d'autorisation, la méthode, le type de contenu et la taille du corps avant de parser le JSON. Placez ensuite le message validé dans votre propre file interne et retournez un code 2xx. L'envoi d'un e-mail, l'appel d'un CRM ou la génération d'un document peut alors se poursuivre sans retenir la connexion HTTP.

Traitez chaque appel comme potentiellement répétable. La classe d'événement et l'horodatage ne forment pas toujours une clé métier suffisante. Cherchez un identifiant stable dans le contenu, par exemple l'identifiant de soumission Forms, puis enregistrez le résultat avant l'action externe. Si la même clé revient, le récepteur doit reconnaître le traitement déjà effectué au lieu de créer un doublon.

Le code stable35 journalise les réponses 2xx, les statuts inattendus et les exceptions, mais sa tâche WebhookCall ne contient pas de boucle de nouvelle tentative. Le récepteur doit donc conserver rapidement le message avant de lancer une opération fragile. Si une reprise automatique est nécessaire, implémentez-la dans votre file de traitement avec un nombre limité d'essais et une file d'échec consultable.

Protégez aussi les données en aval :

• créez un secret différent pour chaque récepteur ;
• refusez les requêtes sans HTTPS en production ;
• n'enregistrez pas le jeton ni le corps complet si celui-ci contient des réponses sensibles ;
• limitez les personnes pouvant lire les messages en erreur ;
• fixez une durée de conservation pour les événements et journaux ;
• prévoyez la révocation du secret et la désactivation de l'inscription.

Comment tester et diagnostiquer un webhook Nextcloud ?

Créez d'abord un récepteur de test qui conserve l'heure, les en-têtes utiles, le code de validation et la classe d'événement, sans afficher publiquement les données reçues. Déclenchez ensuite l'événement avec un compte pilote. Pour Forms, envoyez une soumission fictive qui ne contient aucune donnée réelle.

Vérifiez l'inscription avec occ webhook_listeners:list, puis contrôlez l'exécution des tâches d'arrière-plan. Nextcloud recommande Cron pour les instances utilisées en continu. La documentation indique que la tâche Cron appelle cron.php toutes les cinq minutes dans sa configuration standard. AJAX dépend au contraire de l'activité des utilisateurs et peut retarder les travaux sur une instance peu consultée.

Suivez cette recette avant la production :

1. enregistrer le webhook vers une URL de test en HTTPS ;
2. produire un événement autorisé et confirmer la réception ;
3. produire un événement hors filtre et confirmer son absence ;
4. envoyer un secret incorrect au récepteur et vérifier le refus ;
5. faire retourner temporairement un statut 500 et repérer l'erreur dans les journaux Nextcloud ;
6. rétablir le récepteur, puis rejouer un nouvel événement ;
7. répéter le même message côté récepteur et confirmer l'absence de doublon métier ;
8. supprimer l'inscription de test et vérifier qu'aucun nouvel appel ne part.

Si rien n'arrive, vérifiez dans cet ordre la classe d'événement, le filtre, l'URL, le certificat TLS, le secret, l'accès réseau sortant et les tâches d'arrière-plan. Relevez l'heure exacte du test pour rapprocher les journaux Nextcloud de ceux du récepteur. Une réponse 200 prouve seulement que l'endpoint a accepté la requête, pas que le traitement métier est terminé.

Conclusion

Les webhooks Nextcloud conviennent lorsqu'un service externe doit être prévenu après un événement compatible. Choisissez une classe documentée, limitez son périmètre avec un filtre testé et protégez le récepteur par HTTPS et un secret dédié. Faites répondre l'endpoint rapidement, placez le travail long dans une file interne et rendez le traitement répétable sans doublon. Enfin, contrôlez Cron, les journaux et la procédure de révocation avant d'utiliser des données réelles.

Découvrir l'offre Nextcloud GaprodVérifier la compatibilité de votre intégration avant commande

Sources officielles

• Manuel Nextcloud stable : Webhook Listeners
• Schéma OpenAPI officiel de Webhook Listeners, branche stable35
• Code officiel de l'écoute et de la mise en file des événements, stable35
• Code officiel de l'appel HTTP des webhooks, stable35
• Configuration officielle des tâches d'arrière-plan Nextcloud
• Classes d'événements Forms compatibles avec les webhooks