> For the complete documentation index, see [llms.txt](https://documentation.efalia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.efalia.com/documentations/efalia-process/vue-ensemble-api/webhooks-evenements.md). # Webhooks et Événements Les **webhooks** permettent à Efalia Process de notifier des systèmes externes en temps réel lorsque des événements surviennent dans les workflows : création de document, changement d'état, exécution d'opération, etc. *** ## Principe Un webhook est une **notification HTTP** envoyée automatiquement par Efalia Process vers une URL de votre choix (endpoint de réception) lorsqu'un événement défini se produit. ``` Efalia Process Votre système │ │ │ POST /webhook ────► │ Reçoit les données │ { événement } │ de l'événement │ │ ``` Contrairement à un polling (interrogation périodique de l'API), les webhooks permettent une **architecture événementielle** sans charge inutile sur les deux systèmes. *** ## Configuration ### URL de Réception Autorisée L'URL de réception des webhooks doit correspondre au pattern autorisé dans la configuration du serveur : ``` $CONTEXT_PROCESS/workey/webhook/* ``` {% hint style="warning" %} L'URL de votre endpoint de réception doit être accessible depuis le serveur Efalia Process (connectivité réseau, pare-feu, certificat SSL valide si HTTPS). {% endhint %} ### Configuration dans le Designer Les webhooks se configurent dans le Designer d'Efalia Process, au niveau des **opérations** ou des **états** d'un processus, en définissant : 1. L'**URL cible** (endpoint de réception) 2. Les **événements déclencheurs** (création, changement d'état, opération exécutée…) 3. Le **format** du payload envoyé 📸 **CAPTURE : webhooks-01-configuration-designer.png** > Configuration d'un webhook sur une opération dans le Designer *** ## Événements Disponibles Efalia Process peut envoyer des webhooks pour les événements suivants : | Événement | Déclencheur | | ------------------------ | ------------------------------------------------ | | `document.created` | Création d'un nouveau document dans un processus | | `document.state_changed` | Changement d'état d'un document | | `operation.executed` | Exécution d'une opération sur un document | | `document.deleted` | Suppression d'un document | | `document.updated` | Modification des champs d'un document | *** ## Format du Payload Les webhooks envoient une requête HTTP **POST** avec un corps JSON contenant les informations de l'événement : ```json { "event": "document.state_changed", "timestamp": "2024-03-15T14:32:00Z", "document": { "id": "550e8400-e29b-41d4-a716-446655440000", "processName": "Validation_Facture", "documentType": "Facture", "state": "Validée", "previousState": "En cours de validation", "author": "jean.dupont", "createdAt": "2024-03-14T09:15:00Z" }, "fields": { "Montant": "1250.00", "Fournisseur": "Société ABC", "Numero_Facture": "FAC-2024-0123" } } ``` *** ## Traitement côté Récepteur Votre endpoint de réception doit : 1. **Accepter** les requêtes POST avec Content-Type `application/json` 2. **Répondre rapidement** (HTTP 200 ou 204) — Efalia Process attend une confirmation avant de continuer 3. **Traiter le payload** de manière asynchrone si le traitement est long ```python # Exemple Python Flask from flask import Flask, request, jsonify app = Flask(__name__) @app.route('/webhook/efalia', methods=['POST']) def receive_webhook(): data = request.json event = data.get('event') document_id = data['document']['id'] # Traitement asynchrone recommandé pour les opérations longues process_event_async(event, document_id, data) return jsonify({"status": "received"}), 200 ``` *** ## Sécurisation des Webhooks {% hint style="warning" %} **Authentification recommandée** Sans sécurisation, n'importe qui connaissant votre URL peut envoyer de fausses notifications. Sécurisez votre endpoint. {% endhint %} ### Signature HMAC Configurez un **secret partagé** entre Efalia Process et votre endpoint. Efalia Process signe chaque requête avec ce secret (en-tête `X-Efalia-Signature`). Votre endpoint vérifie la signature avant de traiter le payload. ### Restriction par IP Restreignez l'accès à votre endpoint webhook aux seules adresses IP du serveur Efalia Process. ### Token d'authentification Incluez un token dans l'URL ou dans les en-têtes configurés dans le Designer : ``` https://votre-api.com/webhook?token= ``` *** ## Débogage et Rejeu En cas d'échec (timeout, erreur HTTP côté récepteur), Efalia Process peut être configuré pour retenter l'envoi du webhook après un délai. Pour déboguer, consultez les journaux du serveur Process (`catalina.out`) qui enregistrent les tentatives d'envoi et les réponses reçues. *** ## Questions Fréquentes
Que se passe-t-il si mon endpoint est temporairement indisponible ? Efalia Process peut être configuré pour effectuer des tentatives de renvoi (retry) avec délai exponentiel. Vérifiez la configuration des retries dans les paramètres webhooks de votre installation.
Puis-je filtrer les événements envoyés par webhook ? Oui. Dans le Designer, vous sélectionnez précisément les opérations ou changements d'état qui déclenchent le webhook. Vous pouvez ainsi n'envoyer que les événements pertinents pour votre système.
Les webhooks respectent-ils les droits des utilisateurs ? Les webhooks sont déclenchés par le serveur Efalia Process avec les informations de l'événement, indépendamment des droits utilisateur. Votre endpoint recevra toutes les notifications pour les événements configurés.
*** Pour aller plus loin : * [API REST](/documentations/efalia-process/vue-ensemble-api/documentation-api-rest.md) * [Vue d'Ensemble API](/documentations/efalia-process/vue-ensemble-api.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://documentation.efalia.com/documentations/efalia-process/vue-ensemble-api/webhooks-evenements.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.