# Real Time - Webhooks

## What is a webhook?

A webhook is an automated HTTP request that Daxium-Air sends to a target URL of your choice as soon as an event occurs on the platform — for example, when a submission is created or updated. Instead of another system having to poll Daxium-Air for changes, Daxium-Air pushes the data to that system the moment it becomes available.

## Using webhooks to integrate with other software

Webhooks are a lightweight way to connect Daxium-Air to any external tool that can receive an HTTP request: a CRM, an ERP, a messaging service, a database, a custom internal application, etc.

Once the webhook payload is received at the target URL, the data can be used as-is, or it can first be transformed by a **middleware** (a small service you host yourself) or by a **no-code automation tool** such as [Make](/user-documentation/connect/no-code-connectors/make.md) before being forwarded to the final destination system. This intermediate layer lets you reshape fields, enrich the payload, apply business rules, or fan the data out to several systems at once — without any custom development on the Daxium-Air side.

## Configuration in Daxium-Air

![Webhook configuration via a Daxium-Air automation](/files/TrMJYzItdVO5D3wgHaFn)

Webhooks in Daxium-Air are configured through the [Automations](/user-documentation/build/building-forms/automations.md) feature. Because automations live at the form level, each webhook is set up on the specific form whose submissions you want to push out: you open the form, create an automation, and select **"Send the submission to an external URL"** as its action.

Since webhooks rely on the automation engine, you also need to define **when** they are sent:

* **Trigger** — the event that fires the webhook (for example, a submission being created, updated, or reaching a specific workflow state).
* **Condition** *(optional)* — you can create and attach a [condition](/user-documentation/build/building-forms/conditions.md) so the webhook is only generated when the submission matches the rule you define (e.g. only when a status field equals "Validated", or only for submissions above a certain amount).

Once the trigger and (optional) condition are set, you can finish configuring the action:

* **Listening URL** — the HTTPS endpoint that will receive the webhook payload. This URL is provided by the system on the receiving end (your middleware, your no-code tool, or the third-party application). For a general introduction to webhooks and how a listening URL is set up, see [Make's webhooks documentation](https://help.make.com/webhooks). If you want to quickly create and inspect a listening URL for testing, you can use a free service such as [webhook.site](https://webhook.site), which generates a unique URL on the fly and displays every request it receives.

  <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>Use webhook.site with caution: the URL it generates is <strong>public</strong>. Before using it, make sure you are allowed to expose the data in your submissions externally. For anything containing personal data, customer information, or other sensitive content, use a private endpoint you control instead.</p></div>
* **Header parameters** *(optional)* — you can add one or more custom HTTP headers (key/value pairs) to every request sent by the webhook. This is typically used to pass an authentication token, an API key, or any other metadata the receiving system expects.
* **Issue notification email** *(optional)* — you can specify an email address that will be notified whenever the webhook fails to be delivered (for example, if the listening URL is unreachable or returns an error).

## Payload format

The webhook sends a `POST` request with `Content-Type: application/json` to your listening URL. The body is the full JSON representation of the submission that triggered the event.

### Top-level fields

| Field                             | Type           | Description                                                                                    |
| --------------------------------- | -------------- | ---------------------------------------------------------------------------------------------- |
| `id`                              | UUID           | Submission identifier                                                                          |
| `type`                            | string         | Submission type (e.g. `"simple"`)                                                              |
| `submissionNumber`                | integer        | Sequential submission number                                                                   |
| `vmShort`                         | string         | Short name of the Daxium-Air instance                                                          |
| `title`                           | string \| null | Submission title, if set                                                                       |
| `isTaskModel`                     | boolean        | Whether the submission is a task model                                                         |
| `latitude` / `longitude`          | float \| null  | GPS coordinates of the submission, if captured                                                 |
| `createdAt` / `updatedAt`         | integer        | Creation and last update timestamps (UNIX)                                                     |
| `dataCreatedAt` / `dataUpdatedAt` | integer        | Data-level creation and update timestamps (UNIX)                                               |
| `structure`                       | object         | Form metadata: `id`, `version`, `name`, `hasTriggers`, `isLastVersion`                         |
| `user`                            | object         | User who last modified the submission: `id`, `email`, `first_name`, `last_name`, `groups`      |
| `items`                           | array          | List of all form fields with their values (see below)                                          |
| `settings`                        | object         | Submission settings: `tags`, `task`, `color`, `firstLevel`, etc.                               |
| `currentState`                    | object \| null | Current workflow state if the form has a workflow: `id`, `name` (multilingual), `color`, `end` |
| `defaultImage`                    | UUID \| null   | UUID of the submission's default image, if any                                                 |

### `items` array — field types

Each element in `items` always includes `name` (system name), `type`, `label`, and `value` (when applicable).

| Field type                                                        | `value` format                                                                                                                |
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `text`, `number`, `boolean`, `date`, `email`, `phone`, `duration` | Scalar (string / number / boolean / UNIX timestamp)                                                                           |
| `location`                                                        | `{ lat, lng, address }`                                                                                                       |
| `image`, `signature`, `file`                                      | Array of objects: `{ id, name, size, mimeType, extension }` — **file content is not included; retrieve it via the Files API** |
| `list`                                                            | `{ ids: [...], lists: [{ id, rootId, name, url, color, externalId, imageId }] }` — **fully expanded with names and metadata** |
| `relation`                                                        | `{ submissions: [{ id, structure_id }] }` — **IDs only; retrieve full data via the Submissions API**                          |
| `user`                                                            | Array of `{ id }` objects                                                                                                     |
| `label`, `logo`                                                   | Display-only fields; no `value`                                                                                               |

{% hint style="info" %}
List values are **fully expanded** in the webhook payload (names, colors, external IDs, etc.), unlike the standard Submissions API which returns only IDs by default. Relation and file fields are **not** expanded — use the respective API endpoints to fetch their content.
{% endhint %}

### Authentication

Daxium-Air does not sign webhook payloads. To secure your endpoint, use the **Header parameters** field in the automation to pass an API key or bearer token that your receiving system can validate.

## Delivery and retry behaviour

* Daxium-Air expects an **HTTP 2xx** response from your endpoint within **30 seconds**. Any response outside the 2xx range, or no response within the timeout, is treated as a failure.
* Failed deliveries are **stored in Daxium-Air** and visible in the back office. They can be **retried manually** from there.
* No automatic retry is performed — manual intervention is required for failed calls.

## Report webhook (send report + submission URLs)

In addition to the submission webhook, the **report-sending automation** supports a separate webhook variant that posts the URLs of a generated report and its associated submission once the report is ready:

```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}"
}
```

To configure it, enable **"Send my report to an external URL"** in the report automation and provide the target HTTPS URL. Custom headers and an issue notification email work the same way as for the submission webhook.


---

# 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/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.