--- title: Utiliser les webhooks Apenday description: "Souscrire aux webhooks de rendez-vous, connaître le format et les en-têtes des notifications, et savoir comment y répondre." url: "https://support.apenday.com/support/utiliser-les-webhook-apenday/" updated: "2026-10-27" category: Connecteurs et Synchronisation --- # Utiliser les webhooks Apenday Les webhooks Apenday envoient à votre système une notification à chaque étape de la vie d'un rendez-vous : prise, modification, annulation, clôture et enquête de satisfaction. ## Les types d'événements | Événement | Envoyé quand | | --- | --- | | `meeting_confirmed` | Un rendez-vous est pris | | `meeting_updated` | Le client modifie son rendez-vous, ou un conseiller ou un administrateur le déplace ou le réaffecte. Également envoyé quand les données personnelles du rendez-vous sont anonymisées | | `meeting_cancelled` | Le client annule son rendez-vous | | `meeting_cancelled_by_consultant` | Un conseiller ou un administrateur annule le rendez-vous, dans Apenday ou par l'API | | `meeting_terminated` | Le conseiller marque le rendez-vous comme terminé, dans Apenday ou par l'API | | `meeting_missed` | Le conseiller marque le rendez-vous comme manqué, dans Apenday ou par l'API | | `meeting_rated` | Le client renseigne l'enquête de satisfaction | Un webhook porte sur un seul événement : souscrivez un webhook par événement à suivre. Chaque notification indique son événement dans l'en-tête `X-Apenday-Event`, une même URL peut donc recevoir plusieurs événements. ## Souscrire à un webhook Souscrivez depuis le back-office, comme décrit dans [Gérer vos webhooks depuis le back-office](https://support.apenday.com/support/gerer-vos-webhooks-depuis-le-back-office/), ou par l'API REST ([documentation de la ressource Hooks](https://app.apenday.com/api/docs?ui=re_doc#tag/Hooks)). Par l'API, envoyez une requête **POST** sur `https://app.apenday.com/api/public/hooks`, authentifiée par votre clé d'API (voir [Utiliser l'API Apenday](https://support.apenday.com/support/utiliser-lapi-apenday/)) : ``` POST /api/public/hooks Content-Type: application/json X-AUTH-TOKEN: votre-cle-api { "url": "https://mydomain.com/url-a-notifier", // URL qui recevra les notifications "event": "meeting_confirmed" // Événement à suivre } ``` L'URL doit commencer par `https://` et être accessible depuis Internet. Une URL en `http://` ou pointant vers une adresse privée est refusée avec un code `422`. Exemple de réponse : ``` { "@context": "/api/contexts/Hooks", "@id": "/api/public/hooks/03a84931-3bb6-47b5-8323-336c236a6b93", "@type": "Hooks", "event": "meeting_confirmed", "url": "https://mydomain.com/url-a-notifier", "enabled": true, // false une fois le webhook désactivé "signed": true, // Les notifications de ce webhook sont signées "secret": "9f2c8a...4e71" // Secret de signature, renvoyé uniquement ici } ``` Pour vous désabonner, envoyez une requête **DELETE** sur l'adresse donnée par la propriété `@id` de la réponse. ## Le secret de signature Le champ `secret` de la réponse ci-dessus n'est renvoyé **qu'une seule fois**, par la requête qui vient de créer l'abonnement. Il n'apparaît dans aucune autre réponse de l'API et n'est plus consultable ensuite. Enregistrez-le dans votre système au moment où vous le recevez. Il vous sert à vérifier que les notifications reçues viennent bien d'Apenday et que leur contenu n'a pas été modifié en chemin. La marche à suivre, avec un exemple de vérification complet en PHP et un en JavaScript, est détaillée ici : [Vérifier la signature des notifications de rendez-vous](https://support.apenday.com/support/verifier-la-signature-des-notifications-de-rendez-vous/). ## Le format des notifications Chaque notification est une requête **POST** vers l'URL du webhook, avec les en-têtes suivants : | En-tête | Contenu | | --- | --- | | `Content-Type` | `application/json` | | `X-Apenday-Event` | L'événement, parmi les valeurs du tableau ci-dessus. Exemple : `meeting_confirmed` | | `X-Apenday-Event-Id` | Identifiant unique de l'événement, identique pour toutes les tentatives d'envoi et pour tous les webhooks qui reçoivent cet événement. Exemple : `3f6c1a2e-8d4b-4c7e-9a51-0b2e7d9c4f10` | | `X-Apenday-Event-Timestamp` | Moment de l'événement, en secondes écoulées depuis le 1er janvier 1970, en UTC. Identique pour toutes les tentatives d'envoi. Exemple : `1789479700` | Un webhook signé ajoute les en-têtes `X-Apenday-Timestamp` et `X-Apenday-Signature`, décrits dans [Vérifier la signature des notifications de rendez-vous](https://support.apenday.com/support/verifier-la-signature-des-notifications-de-rendez-vous/). Le corps porte l'état complet du rendez-vous au moment de l'envoi, et non les seuls champs modifiés. Son format est le même pour tous les événements : ``` { "@context": "/api/contexts/Appointment", "@id": "/api/public/appointments/XXXXX", // Adresse du rendez-vous dans l'API publique "@type": "Appointment", "id": "Identifiant_du_rendez-vous", "meeting_id": "Identifiant_de_levenement", "meeting_name": "Nom de l'évènement", "meeting_technical_name": "Nom technique de l'évènement", "meeting_type": "default", // default, call, video ou other "status": "scheduled", // scheduled, cancelled, cancelled_by_consultant, terminated ou missed "date": "2025-06-11T16:30:00+02:00", // date et heure de début "end_date": "2025-06-11T17:15:00+02:00", // date et heure de fin "consultants": [ { "name": "Nom du conseiller", "email": "Adresse email du conseiller", "external_id": null // Votre identifiant de conseiller, s'il est renseigné } ], "customer_firstname": "Prénom du client", // "unknown" si le formulaire ne demande pas ce champ "customer_lastname": "Nom du client", "customer_email": "email du client", "customer_phone_number": "numéro de téléphone", "other_form_values": { // ... autres valeurs du formulaire, puis : "createdAt": "2025-06-01T08:12:00+00:00", // Création du rendez-vous, en UTC "updatedAt": "2025-06-02T06:45:00+00:00" // Dernière mise à jour du rendez-vous, en UTC }, "agency_name": "Nom de l'agence", "agency_id": null, // Identifiant Apenday de l'agence "agency_external_id": null, // Identifiant de l'agence dans votre système "agency_crm_id": null, // Identifiant de l'agence dans votre CRM "satisfaction_score": null, // Note de l'enquête de satisfaction "satisfaction_comment": null, // Commentaire de l'enquête de satisfaction "utm_campain": null, // Paramètres UTM "utm_source": null, // Paramètres UTM "utm_medium": null, // Paramètres UTM "tags": [], // Libellés des tags posés sur le rendez-vous "front_actions": { // URLs des pages publiques du rendez-vous, voir ci-dessous } } ``` ## Le contenu de front_actions Ce bloc rassemble les URLs des pages publiques du rendez-vous. **Les clés présentes varient** selon l'état du rendez-vous et le type d'évènement : ne considérez aucune d'elles comme garantie, et testez sa présence avant de l'utiliser. | Clé | Présente quand | | --- | --- | | `cancel` | Le rendez-vous est encore annulable | | `update` | Le rendez-vous est encore modifiable | | `survey` | Le rendez-vous peut être évalué | | `download_ics` | Le rendez-vous est au statut `scheduled` | | `video_url_user` | Le rendez-vous est une visio au statut `scheduled` : lien de la visio pour le client | | `video_url_consultant` | Le rendez-vous est une visio au statut `scheduled`, selon le paramétrage de l'événement : lien de la visio pour le conseiller | **Le bloc `front_actions` est entièrement absent** de la charge quand aucune action n'est disponible, ce qui est notamment le cas d'un rendez-vous passé. Ne comptez donc pas non plus sur la présence de la clé elle-même. ## Répondre à une notification Répondez par un code `2xx`. Apenday attend la réponse 10 secondes au plus sans activité, et 15 secondes au total : enregistrez la notification, répondez, puis traitez-la. | Réponse de votre système | Effet | | --- | --- | | `2xx` | Notification délivrée | | `410 Gone` | Le webhook est désactivé. Il reste visible dans le back-office, où il se réactive, et une nouvelle souscription du même compte au même événement sur la même URL le réactive aussi | | `5xx`, `408`, `429`, ou aucune réponse | Nouvelle tentative 1 minute, puis 5 minutes, puis 25 minutes après l'échec précédent. Au-delà, la notification est abandonnée | | Tout autre code, redirection `3xx` comprise | Échec enregistré sur le webhook, sans nouvelle tentative. Les redirections ne sont pas suivies | **Une notification peut arriver deux fois**, par exemple si votre système la traite mais répond trop tard. Dédoublonnez sur `X-Apenday-Event-Id`, identique pour toutes les tentatives d'un même événement. **Les notifications ne sont pas garanties dans l'ordre.** Pour un même rendez-vous, identifié par le champ `id`, ignorez une notification dont `X-Apenday-Event-Timestamp` est antérieur à celui de la dernière notification traitée. Cet horodatage est précis à la seconde : en cas d'égalité, relisez le rendez-vous par l'API publique, à l'adresse donnée par `@id`. **Une relance porte l'état courant du rendez-vous.** Le corps est relu à chaque tentative et non figé au moment de l'événement. Une confirmation relancée après une annulation porte donc le statut `cancelled`, alors que `X-Apenday-Event` vaut `meeting_confirmed`. **Modifier l'URL ou l'événement d'un webhook abandonne les envois en attente.** Si vous corrigez l'URL alors qu'une relance est programmée, cette relance n'a pas lieu. Vérifiez les rendez-vous de la période concernée par l'API publique si vous suspectez un manque.