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

# Documents Webhooks

> Learn about documents webhooks.

Documents webhooks notify your system in these scenarios:

* [Document objects](/legacy/api-reference/documents#document-object) are **added**. This happens when the API finds and retrieves documents from a newly-created user account, or when it finds new documents during periodic scanning.
* Document objects are **updated**. Periodic scans detect when a document object is updated with new information.
* Document objects are **removed**. This happens when the user or their employer deletes the documents from a payroll account and the Argyle API does not find them during a periodic scan of the account, or when the user or their employer deletes the payroll account that holds the documents.
* Data extraction has **completed** for a [payroll document scanned by Argyle](/legacy/guides/argyle-link/flows/document-processing#payroll-documents) from a connected account.
* Data extraction has **failed** for a payroll document scanned by Argyle from a connected account.

## Added

**POST** `/v1/webhooks`

Implement the `documents.added` webhook to know when a document object is added.

* Document objects are **added** when the API finds and retrieves documents from a newly-created user account, or when it finds new documents during periodic scanning.

### Request body

### Webhook message

* `name` (string, optional): Name used for the webhook subscription.
* `data` (object, optional)
* `account` (string (uuid), optional): ID of the account.
* `user` (string (uuid), optional): ID of the user.
* `document` (string (uuid), optional): ID of the document.

<Tabs>
  <Tab title="curl">
    ```bash theme={}
    curl --request POST \\
    --url https://api.argyle.com/v1/webhooks \\
    --header 'accept: application/json' \\
    --header 'content-type: application/json' \\
    --data '{
    "events": ["documents.added"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret"
    }'
    ```
  </Tab>

  <Tab title="python">
    ```python theme={}
    import requests
    url = "https://api.argyle.com/v1/webhooks"
    payload = {
    "events": ["documents.added"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret"
    }
    headers = {
    "accept": "application/json",
    "content-type": "application/json"
    }
    response = requests.post(url, json=payload, headers=headers)
    ```
  </Tab>
</Tabs>

```json theme={}

{
"event": "documents.added",
"name": "A document was added",
"data": {
"account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3",
"document": "4334r6e-a964-45eef6-b201-64464"
}
},
null,
2

```

<RefSubLayout.Divider />

## Updated

**POST** `/v1/webhooks`

Implement the `documents.updated` webhook to know when a document object is updated.

* Document objects are **updated** through periodic scanning.

### Request body

### Webhook message

* `name` (string, optional): Name used for the webhook subscription.
* `data` (object, optional)
* `account` (string (uuid), optional): ID of the account.
* `user` (string (uuid), optional): ID of the user.
* `document` (string (uuid), optional): ID of the document.

<Tabs>
  <Tab title="curl">
    ```bash theme={}
    curl --request POST \\
    --url https://api.argyle.com/v1/webhooks \\
    --header 'accept: application/json' \\
    --header 'content-type: application/json' \\
    --data '{
    "events": ["documents.updated"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret"
    }'
    ```
  </Tab>

  <Tab title="python">
    ```python theme={}
    import requests
    url = "https://api.argyle.com/v1/webhooks"
    payload = {
    "events": ["documents.updated"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret"
    }
    headers = {
    "accept": "application/json",
    "content-type": "application/json"
    }
    response = requests.post(url, json=payload, headers=headers)
    ```
  </Tab>
</Tabs>

```json theme={}

{
"event": "documents.updated",
"name": "A document was updated",
"data": {
"account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3",
"document": "4334r6e-a964-45eef6-b201-64464"
}
},
null,
2

```

<RefSubLayout.Divider />

## Removed

**POST** `/v1/webhooks`

Implement the `documents.removed` webhook to know when a document object is removed.

Document objects are removed when:

* The user or their employer deletes the documents from a payroll account and the Argyle API does not find them during a periodic scan of the account.
* The user or their employer deletes the payroll account that holds the documents.

### Request body

### Webhook message

* `name` (string, optional): Name used for the webhook subscription.
* `data` (object, optional)
* `account` (string (uuid), optional): ID of the account.
* `user` (string (uuid), optional): ID of the user.
* `document` (string (uuid), optional): ID of the document.

<Tabs>
  <Tab title="curl">
    ```bash theme={}
    curl --request POST \\
    --url https://api.argyle.com/v1/webhooks \\
    --header 'accept: application/json' \\
    --header 'content-type: application/json' \\
    --data '{
    "events": ["documents.removed"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret"
    }'
    ```
  </Tab>

  <Tab title="python">
    ```python theme={}
    import requests
    url = "https://api.argyle.com/v1/webhooks"
    payload = {
    "events": ["documents.removed"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret"
    }
    headers = {
    "accept": "application/json",
    "content-type": "application/json"
    }
    response = requests.post(url, json=payload, headers=headers)
    ```
  </Tab>
</Tabs>

```json theme={}

{
"event": "documents.removed",
"name": "A document was removed",
"data": {
"account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3",
"document": "4334r6e-a964-45eef6-b201-64464"
}
},
null,
2

```

<RefSubLayout.Divider />

## OCR completed

**POST** `/v1/webhooks`

Implement the `documents.ocr_completed` webhook to know when OCR is completed for scanned documents.

* The `documents.ocr_completed` webhook notifies your system when data retrieval through OCR is **completed** for a document scanned by Argyle from a connected account.
* Use this webhook to get updates when OCR is completed for documents that are initially scanned from a newly connected account, or when OCR is completed for documents that are added or updated through periodic scanning.

<Note>
  The payload provided by this webhook does not include the actual metadata contents of the document. You can request this through the `/documents` endpoint, by calling GET `/documents/{id}` with the document ID received in the `documents.ocr_completed` webhook. *For more information, refer to the OCR Data fields page.*
</Note>

### Request body

### Webhook message

* `name` (string, optional): Name used for the webhook subscription.
* `data` (object, optional)
* `account` (string (uuid), optional): ID of the account.
* `user` (string (uuid), optional): ID of the user.
* `document` (string (uuid), optional): ID of the document.

<Tabs>
  <Tab title="curl">
    ```bash theme={}
    curl --request POST \\
    --url https://api.argyle.com/v1/webhooks \\
    --header 'accept: application/json' \\
    --header 'content-type: application/json' \\
    --data '{
    "events": ["documents.ocr_completed"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret"
    }'
    ```
  </Tab>

  <Tab title="python">
    ```python theme={}
    import requests
    url = "https://api.argyle.com/v1/webhooks"
    payload = {
    "events": ["documents.ocr_completed"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret"
    }
    headers = {
    "accept": "application/json",
    "content-type": "application/json"
    }
    response = requests.post(url, json=payload, headers=headers)
    ```
  </Tab>
</Tabs>

```json theme={}

{
"event": "documents.ocr_completed",
"name": "OCR is completed",
"data": {
"account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3",
"document": "4334r6e-a964-45eef6-b201-64464"
}
},
null,
2

```

<RefSubLayout.Divider />

## OCR failed

**POST** `/v1/webhooks`

Implement the `documents.ocr_failed` webhook to know when OCR fails for a scanned document.

* The `documents.ocr_failed` webhook notifies your system when data retrieval through OCR has failed for a document scanned by Argyle from a connected account.
* If OCR fails, the scanned document's `metadata` field returns an `ocr_data` object with the specific type of `error`. *Consult [OCR data fields](/legacy/api-reference/documents#object-ocr_data) for more information about possible error types.*

### Request body

### Webhook message

* `name` (string, optional): Name used for the webhook subscription.
* `data` (object, optional)
* `account` (string (uuid), optional): ID of the account.
* `user` (string (uuid), optional): ID of the user.
* `document` (string (uuid), optional): ID of the document.

<Tabs>
  <Tab title="curl">
    ```bash theme={}
    curl --request POST \\
    --url https://api.argyle.com/v1/webhooks \\
    --header 'accept: application/json' \\
    --header 'content-type: application/json' \\
    --data '{
    "events": ["documents.ocr_failed"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret"
    }'
    ```
  </Tab>

  <Tab title="python">
    ```python theme={}
    import requests
    url = "https://api.argyle.com/v1/webhooks"
    payload = {
    "events": ["documents.ocr_failed"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret"
    }
    headers = {
    "accept": "application/json",
    "content-type": "application/json"
    }
    response = requests.post(url, json=payload, headers=headers)
    ```
  </Tab>
</Tabs>

```json theme={}

{
"event": "documents.ocr_failed",
"name": "OCR has failed",
"data": {
"account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3",
"document": "4334r6e-a964-45eef6-b201-64464"
}
},
null,
2

```