> For the complete documentation index, see [llms.txt](https://api.dataloy.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.dataloy.com/dataloy-rest-api/webhooks.md).

# Webhooks

## Webhooks

Webhooks are HTTP callbacks that notify your application when Dataloy objects change. You subscribe through the `WebhookSubscription` resource, and Dataloy sends an HTTP POST for every matching event.

* Notifications are **asynchronous**, and their **order is not guaranteed**.

### Event types

An event type is made of:

| Part                  | Values                             | Example                       |
| --------------------- | ---------------------------------- | ----------------------------- |
| Object type           | Any Dataloy resource name          | `Voyage`, `Cargo`, `Document` |
| Operation             | `C` create, `U` update, `D` delete | `U`                           |
| Object key (optional) | Primary key of one object          | `793628`                      |

| Subscription      | Notifies when                         |
| ----------------- | ------------------------------------- |
| `Cargo.C`         | any Cargo is created                  |
| `Document.D`      | any Document is deleted               |
| `Voyage.U`        | any Voyage is updated                 |
| `Voyage.U.793628` | the Voyage with key 793628 is updated |

### Managing webhooks in the Dataloy client

The **Webhooks** page in the Dataloy client (under **Alerts**) is the easiest way to work with webhooks:

* **Create subscriptions with a guided form** that sets up the trigger, the endpoint, authentication and the payload, and builds the filter expression for you.
* **See all subscriptions in one place**, filter them, and view or edit their details.
* **See the notifications** sent for each subscription: when they were delivered, how many attempts they took and which ones failed.

### Creating a subscription

`POST /WebhookSubscription`

```json
{
  "eventType": "U",
  "user": 999999,
  "objectType": "BunkerOrder",
  "channelInfo": {
    "channelType": "HTTP",
    "url": "https://example.com/webhook",
    "authType": "API_KEY",
    "apiKeyKey": "X-API-Key",
    "apiKeyValue": "my-secret-key"
  }
}
```

#### Channels

Where the notification goes is set in `channelInfo`: set `channelType` to `HTTP` and `url` to the endpoint the notification is POSTed to.

#### HTTP headers

To send your own headers with each notification, add them to `channelInfo.httpRequestParams`:

```json
"channelInfo": {
  "channelType": "HTTP",
  "url": "https://example.com/webhook",
  "authType": "NONE",
  "httpRequestParams": [
    { "parameterName": "X-Tenant", "parameterValue": "acme" }
  ]
}
```

### Authentication

An HTTP channel authenticates to your endpoint as its `authType` says. Only the credentials of that type are used.

| `authType`     | Fields on `channelInfo`    | Sent as                                                         |
| -------------- | -------------------------- | --------------------------------------------------------------- |
| `NONE`         | none                       | No authentication                                               |
| `BASIC`        | `userName`, `password`     | `Authorization: Basic …`                                        |
| `ACCESS_TOKEN` | `accessToken`              | `Authorization: Bearer <accessToken>`                           |
| `OAUTH2`       | see OAuth 2.0              | `Authorization: Bearer <token fetched from the token endpoint>` |
| `API_KEY`      | `apiKeyKey`, `apiKeyValue` | `<apiKeyKey>: <apiKeyValue>` header                             |

#### OAuth 2.0

With `OAUTH2`, Dataloy requests a token from your token endpoint, caches it, and requests a new one shortly before it expires.

| Field                           | Description                                                                                                                       |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `accessTokenRequestUrl`         | Token endpoint                                                                                                                    |
| `accessTokenRequestBody`        | Request body, **Base64 encoded** (for instance the client-credentials JSON)                                                       |
| `accessTokenRequestContentType` | Content type of the token request (optional)                                                                                      |
| `accessTokenRequestHttpMethod`  | `POST` (default)                                                                                                                  |
| `accessTokenRequestHttpHeaders` | Extra headers for the token request, as `Name=value\|Name2=value2` (optional)                                                     |
| `accessTokenRequestTokenPath`   | Where the token is in the response: a JsonPath such as `$.data.token`, or `$body` for the whole response. Default: `access_token` |
| `accessTokenRequestTimeToLive`  | Token lifetime in seconds. Default: `expires_in` from the response                                                                |

```json
"channelInfo": {
  "channelType": "HTTP",
  "url": "https://example.com/webhook",
  "authType": "OAUTH2",
  "accessTokenRequestUrl": "https://auth.example.com/oauth/token",
  "accessTokenRequestBody": "eyJjbGllbnRfaWQiOiIuLi4iLCJjbGllbnRfc2VjcmV0IjoiLi4uIiwiZ3JhbnRfdHlwZSI6ImNsaWVudF9jcmVkZW50aWFscyJ9"
}
```

Changes to the OAuth settings take effect on the next notification.

#### Legacy fields on the subscription

`url`, `webhookUsername`, `webhookPassword`, `accessToken`, `accessTokenRequestUrl` and `accessTokenRequestBody` can still be sent directly on the `WebhookSubscription`. They are copied to `channelInfo`, and the `authType` is worked out from them. New integrations should use `channelInfo`.

### Notification payload

The notification is a JSON object in the body of the POST:

```json
{
  "id": "1573335-244070007",
  "eventTime": "2016-09-14T13:37:26",
  "objectType": "PortCall",
  "eventType": "U",
  "dataloyObject": 189126972,
  "dataloyObjectSelf": "https://<host>/ws/rest/PortCall/189126972",
  "subscription": {
    "key": 243885046,
    "self": "https://<host>/ws/rest/WebhookSubscription/243885046",
    "objectType": "BunkerOrder",
    "dataloyObject": 244070007,
    "eventType": "U",
    "url": "https://example.com/webhook"
  },
  "resource": {
    "key": 244070007,
    "self": "https://<host>/ws/rest/BunkerOrder/244070007",
    "exchangeRate": 3.0,
    "portCall": { "key": 189126972, "self": "https://<host>/ws/rest/PortCall/189126972" },
    "...": "..."
  }
}
```

| Attribute           | Description                                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| `id`                | Unique identifier of the notification                                                                   |
| `eventTime`         | When the event occurred                                                                                 |
| `objectType`        | Type of the changed object                                                                              |
| `eventType`         | `C`, `U` or `D`                                                                                         |
| `dataloyObject`     | Key of the changed object. It can differ from the subscribed object when the change is in its hierarchy |
| `dataloyObjectSelf` | URL of the changed object                                                                               |
| `subscription`      | The subscription that matched                                                                           |
| `resource`          | The subscribed object                                                                                   |

### Subscription options

| Attribute                                 | Description                                                                                                                                                                                                                                                                                  |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `json`                                    | Fields to include in `resource`, **Base64 encoded**, in the format of [Adjust Number of Fields to be Returned from a Request](https://api.dataloy.com/dataloy-rest-api/adjust-number-of-fields-to-be-returned-from-a-request). For instance `{"extraCost":"*"}` → `eyJleHRyYUNvc3QiOiIqIn0=` |
| `expression`                              | Condition tree that must be true for the notification to be sent (see below)                                                                                                                                                                                                                 |
| `dlpAlertScript`, `scriptParameterValues` | Filter with a script                                                                                                                                                                                                                                                                         |
| `onlyMainObject`                          | `true`: notify only changes to the subscribed object, not its hierarchy                                                                                                                                                                                                                      |
| `rawObject`                               | `true`: send only the object, without the envelope above                                                                                                                                                                                                                                     |
| `notSendMyChange`                         | `true`: don't notify changes made by the subscription's own user                                                                                                                                                                                                                             |

#### Filtering with expressions

`expression` holds a condition, and a notification is only sent when the condition is true for the changed object. Conditions can compare a field with a value, or with the field's value before the change.

Build the expression with the [Expression Builder](https://api.dataloy.com/dataloy-rest-api/webhooks/expression-bui) and send its output as the `expression` string. The format is generated by the builder, so don't write it by hand.

### Retries and deactivation

A notification fails when your endpoint can't be reached, times out or doesn't return a 2xx. Failed notifications are retried with **exponential backoff**: the delay between retries grows with each attempt, from about a minute up to a day.

* By default a notification is retried **5 times**. The number of retries and how often retries run can be configured.
* Notifications are retried oldest first. When one notification for a subscription fails, the subscription's other notifications wait for the next run.
* Responses `400`, `401`, `403`, `404`, `405`, `413` and `422` are **not retried**, since retrying won't fix them. Correct the request or the configuration.

When a notification has failed on its last retry, the subscription is **deactivated**. A subscription with an empty or invalid URL is deactivated at once. A deactivated subscription can't be reactivated, so create a new one.

`POST /WebhookSubscription/sendFailedNotifications` starts a retry run straight away. The backoff still applies.

### Unsubscribing

To stop a subscription, send `PUT /WebhookSubscription/{key}` with:

```json
{ "unsubscribed": true }
```

An unsubscribed subscription can't be updated or reactivated. Create a new subscription if you need it again.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://api.dataloy.com/dataloy-rest-api/webhooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
