# Webhooks

Using webhooks (see <https://en.wikipedia.org/wiki/Webhook>), you can have your external systems notified in real time when specific events occur in your atfinity tenant.

When a trigger fires, atfinity sends an HTTP `POST` request to the URL(s) you have configured for that trigger. The request body is a JSON object and the following headers are always included:

| Header               | Description                                |
| -------------------- | ------------------------------------------ |
| `Content-Type`       | `application/json; charset=UTF-8`          |
| `X-atfinity-event`   | The trigger name (e.g. `case_created`)     |
| `X-atfinity-version` | The atfinity version that sent the request |

## Triggers

The following triggers are available. Each trigger can be configured independently with one or more target URLs.

| Trigger                  | When it fires                                               |
| ------------------------ | ----------------------------------------------------------- |
| `case_created`           | A new case is created                                       |
| `case_approved`          | A case is approved                                          |
| `case_declined`          | A case is declined                                          |
| `case_finished`          | A case is finished                                          |
| `case_comment`           | A comment is added to a case                                |
| `case_changed`           | Data within a case is changed                               |
| `case_state_changed`     | A case transitions to a different state                     |
| `case_documents_updated` | Documents on a case are generated or deleted                |
| `case_proofs_updated`    | Proofs (file attachments) on a case are uploaded or deleted |

## Payload

Every webhook request contains a JSON body with the following fields:

| Field                   | Type            | Description                                       |
| ----------------------- | --------------- | ------------------------------------------------- |
| `trigger`               | string          | The trigger name (e.g. `case_created`)            |
| `case_id`               | integer         | Internal ID of the case                           |
| `case_user_readable_id` | string          | Human-readable case identifier                    |
| `case_name`             | string          | Display name of the case                          |
| `case_url`              | string          | URL to open the case in the atfinity UI           |
| `case_version`          | integer         | Current version number of the case                |
| `case_color`            | string \| null  | Color label assigned to the case, or `null`       |
| `outcome_instance_id`   | integer \| null | ID of the outcome instance, or `null`             |
| `process_key`           | string \| null  | Key of the process the case belongs to, or `null` |

### Additional fields by trigger

#### `case_changed`

| Field    | Type   | Description                                   |
| -------- | ------ | --------------------------------------------- |
| `action` | string | What kind of change occurred (e.g. `updated`) |

#### `case_state_changed`

| Field                | Type           | Description                                            |
| -------------------- | -------------- | ------------------------------------------------------ |
| `previous_state_key` | string \| null | Key of the state the case was in before the transition |
| `current_state_key`  | string \| null | Key of the state the case has transitioned to          |
| `transition_key`     | string \| null | Key of the transition that was used                    |

#### `case_documents_updated`

| Field           | Type             | Description                                                  |
| --------------- | ---------------- | ------------------------------------------------------------ |
| `document_keys` | array of strings | Keys of the documents that were affected                     |
| `action`        | string \| null   | What happened to the documents (e.g. `generated`, `deleted`) |

## Example payload

```json
{
  "trigger": "case_state_changed",
  "case_id": 42,
  "case_user_readable_id": "KYC-0042",
  "case_name": "Acme Corp",
  "case_url": "https://your-tenant.atfinity.app/cases/42",
  "case_version": 7,
  "case_color": "green",
  "outcome_instance_id": 17,
  "process_key": "kyc_process",
  "previous_state_key": "in_review",
  "current_state_key": "approved",
  "transition_key": "approve"
}
```


---

# 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://docs.atfinity.io/api/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.