> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rimdian.com/llms.txt
> Use this file to discover all available pages before exploring further.

# App data hooks

Apps can [register data hooks](/apps-development/app-manifest-reference#data-hook) that will be called by Rimdian when specific events occur.

As opposed to [tasks](/apps-development/tasks) that are executed in the background, data hooks are called in real-time in the [data processing pipeline](/data-lifecycle#data-pipeline) and are expected to return a response within a few seconds.

A common use case for data hooks is to enrich or transform data before it is inserted by Rimdian, or to forward data to a third-party system.

## Data hooks types

Rimdian supports the following data hook types:

* `on_success` - called when a data log item is successfully processed (created, updated...).
* `on_validation` - called when a data log item about to be validated (before it is processed), and can be used to enrich/transform/reject the data item.

## Hook on\_success

<Tip>It is important to return a response within **7 seconds**. If the response is not received within a few seconds, the data hook will be retried 3 times before being dropped!</Tip>

When a `on_success` data hook is called, Rimdian will send a POST request to your app `webhook_endpoint` with the following payload:

```json theme={null}
{
    "api_endpoint": "https://RIMDIAN_API_ENDPOINT",
    "collector_endpoint": "https://RIMDIAN_COLLECTOR_ENDPOINT",
    "workspace_id": "acme_workspace1",
    "app_id": "app_myapp",
    "app_state": {
        "key1": "value1",
        "key2": "value2"
    },
    "kind": "data_hook",
    "data_hook": {
        "data_hook_id": "app_myapp_onsuccess",
        "data_hook_name": "Forward data on success",
        "data_hook_on": "on_success",
        "data_log_id": "1234567890",
        "data_log_kind": "order",
        "data_log_action": "create",
        "data_log_item": "{ ... raw JSON item string ... }",
        "data_log_item_id": "xxxxxxxxx",
        "data_log_item_external_id": "order_123",
        "user": {
            "id": "xxxxxx",
            "external_id": "user_123",
            "is_authenticated": true,
            "created_at": "2024-01-01T00:00:00Z",
            "updated_at": "2024-01-01T00:00:00Z",
            "email": "john@website.com",
            "first_name": "John",
            "last_name": "Doe",
            "phone": "+1234567890",
            "country": "US",
            "language": "en",
            "timezone": "America/New_York",
            ... other user properties
        }
    }
}
```

The full `user` object will be included if the data log item is associated with a user.

The `data_log_item` is the JSON-escaped string value of the item sent to the Collector.

### Expected response

```json theme={null}
{
    "is_done": true,
    "is_error": false,
    "message": "done"
}
```

Returning `is_done` as `false` will cause the data hook to be retried.

## Hook on\_validation

<Tip>It is important to return a response within **5 seconds**. If the response is not received within a few seconds, the data hook won't be retried!</Tip>

When a `on_validation` data hook is called, Rimdian will send a POST request to your app `webhook_endpoint` with the following payload:

```json theme={null}
{
    "api_endpoint": "https://RIMDIAN_API_ENDPOINT",
    "collector_endpoint": "https://RIMDIAN_COLLECTOR_ENDPOINT",
    "workspace_id": "acme_workspace1",
    "app_id": "app_myapp",
    "app_state": {
        "key1": "value1",
        "key2": "value2"
    },
    "kind": "data_hook",
    "data_hook": {
        "data_hook_id": "app_myapp_onvalidation",
        "data_hook_name": "Enrich data on validation",
        "data_hook_on": "on_validation",
        "data_log_id": "1234567890",
        "data_log_kind": "order",
        "data_log_item": "{ ... raw JSON item string ... }"
    }
}
```

The `data_log_item` is the JSON-escaped string value of the item sent to the Collector.

### Expected response for rejecting the data

```json theme={null}
{
    "action": "reject",
    "message": "Optional message to explain why the data was rejected"
}
```

### Expected response for enriching the data

```json theme={null}
{
    "action": "update",
    "message": "Optional message to explain why the data was updated",
    "updated_item": "{ ... raw updated JSON item string ... }"
}
```

<Tip>The `updated_item` field should be a JSON string and not a JSON object.</Tip>

### Expected response for accepting the data

You just need to return a `200 OK` status code with an empty body to accept the data.