# Temps réel - Webhooks

## Qu'est-ce qu'un webhook ?

Un webhook est une requête HTTP automatisée que Daxium-Air envoie vers une URL cible de votre choix dès qu'un événement survient sur la plateforme — par exemple lors de la création ou de la mise à jour d'une fiche. Plutôt qu'un autre système doive interroger Daxium-Air pour connaître les changements, Daxium-Air pousse les données vers ce système dès qu'elles sont disponibles.

## Utiliser les webhooks pour intégrer d'autres logiciels

Les webhooks sont un moyen léger de connecter Daxium-Air à n'importe quel outil externe capable de recevoir une requête HTTP : un CRM, un ERP, un service de messagerie, une base de données, une application interne sur mesure, etc.

Une fois le payload du webhook reçu à l'URL cible, les données peuvent être utilisées telles quelles, ou d'abord transformées par un **middleware** (un petit service que vous hébergez vous-même) ou par un **outil d'automatisation no-code** tel que [Make](/user-documentation/documentation-utilisateur/connect/no-code-connectors/make.md), avant d'être transmises au système de destination final. Cette couche intermédiaire vous permet de remodeler les champs, d'enrichir le payload, d'appliquer des règles métier ou de diffuser les données vers plusieurs systèmes à la fois — sans aucun développement spécifique côté Daxium-Air.

## Configuration dans Daxium-Air

![Configuration du webhook via une automatisation Daxium-Air](/files/TrMJYzItdVO5D3wgHaFn)

Les webhooks dans Daxium-Air se configurent via la fonctionnalité [Automatisations](/user-documentation/documentation-utilisateur/build/building-forms/automations.md). Les automatisations étant définies au niveau du formulaire, chaque webhook est mis en place sur le formulaire spécifique dont vous souhaitez pousser les fiches : ouvrez le formulaire, créez une automatisation, et sélectionnez **« Envoyer la fiche vers une URL externe »** comme action.

Comme les webhooks s'appuient sur le moteur d'automatisation, vous devez également définir **quand** ils sont envoyés :

* **Déclencheur** — l'événement qui déclenche le webhook (par exemple la création ou la mise à jour d'une fiche, ou l'atteinte d'un état de workflow spécifique).
* **Condition** *(optionnelle)* — vous pouvez créer et attacher une [condition](/user-documentation/documentation-utilisateur/build/building-forms/conditions.md) afin que le webhook ne soit généré que lorsque la fiche correspond à la règle que vous définissez (par exemple uniquement lorsqu'un champ statut vaut « Validé », ou uniquement pour les fiches dépassant un certain montant).

Une fois le déclencheur et la condition (facultative) définis, vous pouvez terminer la configuration de l'action :

* **URL d'écoute** — le point de terminaison HTTPS qui recevra le payload du webhook. Cette URL est fournie par le système de réception (votre middleware, votre outil no-code ou l'application tierce). Pour une introduction générale aux webhooks et à la mise en place d'une URL d'écoute, consultez la [documentation Make sur les webhooks](https://help.make.com/webhooks). Pour créer et inspecter rapidement une URL d'écoute à des fins de test, vous pouvez utiliser un service gratuit comme [webhook.site](https://webhook.site), qui génère une URL unique à la volée et affiche chaque requête qu'elle reçoit.

  <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>Utilisez webhook.site avec précaution : l'URL générée est <strong>publique</strong>. Avant de l'utiliser, assurez-vous que vous avez le droit d'exposer les données de vos fiches à l'extérieur. Pour tout contenu contenant des données personnelles, des informations client ou d'autres éléments sensibles, utilisez plutôt un point de terminaison privé que vous contrôlez.</p></div>
* **Paramètres d'en-tête** *(optionnels)* — vous pouvez ajouter un ou plusieurs en-têtes HTTP personnalisés (paires clé/valeur) à chaque requête envoyée par le webhook. Cela est généralement utilisé pour transmettre un jeton d'authentification, une clé d'API ou toute autre métadonnée attendue par le système de réception.
* **E-mail de notification en cas d'incident** *(optionnel)* — vous pouvez préciser une adresse e-mail qui sera notifiée chaque fois que le webhook ne peut pas être délivré (par exemple si l'URL d'écoute est inaccessible ou renvoie une erreur).

## Format du payload

Le webhook envoie une requête `POST` avec `Content-Type: application/json` vers votre URL d'écoute. Le corps de la requête est la représentation JSON complète de la fiche qui a déclenché l'événement.

### Champs de premier niveau

| Champ                             | Type           | Description                                                                                          |
| --------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------- |
| `id`                              | UUID           | Identifiant de la fiche                                                                              |
| `type`                            | string         | Type de fiche (ex. `"simple"`)                                                                       |
| `submissionNumber`                | integer        | Numéro séquentiel de la fiche                                                                        |
| `vmShort`                         | string         | Nom court de l'instance Daxium-Air                                                                   |
| `title`                           | string \| null | Titre de la fiche, si défini                                                                         |
| `isTaskModel`                     | boolean        | Indique si la fiche est un modèle de tâche                                                           |
| `latitude` / `longitude`          | float \| null  | Coordonnées GPS de la fiche, si capturées                                                            |
| `createdAt` / `updatedAt`         | integer        | Timestamps de création et de dernière modification (UNIX)                                            |
| `dataCreatedAt` / `dataUpdatedAt` | integer        | Timestamps de création et modification des données côté serveur (UNIX)                               |
| `structure`                       | object         | Métadonnées du formulaire : `id`, `version`, `name`, `hasTriggers`, `isLastVersion`                  |
| `user`                            | object         | Utilisateur ayant modifié la fiche en dernier : `id`, `email`, `first_name`, `last_name`, `groups`   |
| `items`                           | array          | Liste de tous les champs du formulaire avec leurs valeurs (voir ci-dessous)                          |
| `settings`                        | object         | Paramètres de la fiche : `tags`, `task`, `color`, `firstLevel`, etc.                                 |
| `currentState`                    | object \| null | État courant du workflow si le formulaire en possède un : `id`, `name` (multilingue), `color`, `end` |
| `defaultImage`                    | UUID \| null   | UUID de l'image par défaut de la fiche, le cas échéant                                               |

### Tableau `items` — types de champs

Chaque élément de `items` contient toujours `name` (nom système), `type`, `label` et `value` (si applicable).

| Type de champ                                                     | Format de `value`                                                                                                                       |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `text`, `number`, `boolean`, `date`, `email`, `phone`, `duration` | Scalaire (string / number / boolean / timestamp UNIX)                                                                                   |
| `location`                                                        | `{ lat, lng, address }`                                                                                                                 |
| `image`, `signature`, `file`                                      | Tableau d'objets : `{ id, name, size, mimeType, extension }` — **le contenu du fichier n'est pas inclus ; à récupérer via l'API Files** |
| `list`                                                            | `{ ids: [...], lists: [{ id, rootId, name, url, color, externalId, imageId }] }` — **entièrement développé avec noms et métadonnées**   |
| `relation`                                                        | `{ submissions: [{ id, structure_id }] }` — **identifiants uniquement ; à récupérer via l'API Submissions**                             |
| `user`                                                            | Tableau d'objets `{ id }`                                                                                                               |
| `label`, `logo`                                                   | Champs d'affichage uniquement ; pas de `value`                                                                                          |

{% hint style="info" %}
Les valeurs de type liste sont **entièrement développées** dans le payload du webhook (noms, couleurs, identifiants externes, etc.), contrairement à l'API Submissions standard qui retourne uniquement les identifiants par défaut. Les champs de type relation et fichier ne sont **pas** développés — utilisez les endpoints API correspondants pour en récupérer le contenu.
{% endhint %}

### Authentification

Daxium-Air ne signe pas les payloads des webhooks. Pour sécuriser votre endpoint, utilisez le champ **Paramètres d'en-tête** dans l'automatisation pour transmettre une clé d'API ou un jeton bearer que votre système récepteur pourra valider.

## Comportement en cas d'échec et nouvelles tentatives

* Daxium-Air attend une réponse **HTTP 2xx** de votre endpoint dans un délai de **30 secondes**. Toute réponse en dehors de la plage 2xx, ou l'absence de réponse dans ce délai, est considérée comme un échec.
* Les envois en échec sont **enregistrés dans Daxium-Air** et visibles dans le back office. Ils peuvent être **relancés manuellement** depuis cet espace.
* Aucune nouvelle tentative automatique n'est effectuée — une intervention manuelle est nécessaire pour les appels échoués.

## Webhook de rapport (envoi des URLs rapport + fiche)

En complément du webhook de fiche, l'**automatisation d'envoi de rapport** propose une variante de webhook qui envoie les URLs du rapport généré et de la fiche associée dès que le rapport est prêt :

```json
{
  "report": "https://api.daxium-air.com/{app_short}/reports/{report_id}/results/{file_uuid}",
  "submission": "https://api.daxium-air.com/{app_short}/submissions/{submission_id}"
}
```

Pour le configurer, activez **« Envoyer mon rapport vers une URL externe »** dans l'automatisation de rapport et renseignez l'URL HTTPS cible. Les en-têtes personnalisés et l'e-mail de notification en cas d'incident fonctionnent de la même façon que pour le webhook de fiche.


---

# Agent Instructions: 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:

```
GET https://www.center.daxium-air.com/user-documentation/documentation-utilisateur/connect/exporting-data/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.