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

# Forms Webhooks

> Learn about forms webhooks.

Forms webhooks notify your system when:

* A user **submits** a form, which can be either:
* When a user uploads employment documents
* When a user submits the **Can't find your payroll provider** form after they cannot find their employer or payroll provider
* A user **removes** all previously uploaded documents.
* Third party OCR is **completed** for documents uploaded by a user.
* Third party OCR has **failed** for documents uploaded by a user.

## Submitted

**POST** `/v1/webhooks`

Implement the `forms.submitted` webhook to know when a form object is submitted.

* This webhook is triggered when a user **submits** a form — for example, when a user uploads employment documents and submits the form, or answers and submits an income source form.

### 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.
* `form` (string (uuid), optional): ID of the form.

<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": ["forms.submitted"],
    "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": ["forms.submitted"],
    "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": "forms.submitted",
"name": "Form object was submitted.",
"data": {
"account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3",
"form": "ada143be-3c90-4534-b7ea-9899674dc6e0"
}
},
null,
2

```

<RefSubLayout.Divider />

## Removed

**POST** `/v1/webhooks`

Implement the `forms.removed` webhook to know when a form object is removed.

* This webhook is triggered when a user **removes** all previously uploaded 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.
* `form` (string (uuid), optional): ID of the form.

<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": ["forms.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": ["forms.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": "forms.removed",
"name": "Form object was removed.",
"data": {
"account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3",
"form": "ada143be-3c90-4534-b7ea-9899674dc6e0"
}
},
null,
2

```

<RefSubLayout.Divider />

## OCR completed

**POST** `/v1/webhooks`

Implement the `forms.ocr_completed` webhook to know when third party OCR is completed for uploaded documents.

* The `forms.ocr_completed` webhook notifies your system when data retrieval through third party OCR is completed for documents [manually uploaded](/legacy/guides/argyle-link/flows/document-processing#uploaded-documents) by users through Link.
* The payload provided by this webhook does not include the actual metadata contents of the document. You can request these through the `/forms` endpoint, by calling GET `/forms/{id}` with the form ID received in the `forms.ocr_completed` webhook.

<Note>
  This webhook triggers when OCR is successful for at least one out of all documents within an upload form. If OCR fails for one or more of the remaining documents, the `metadata` field of each failed document returns an `ocr_data` object with the specific type of `error`. *Consult [processing errors - third party OCR](/legacy/guides/argyle-link/flows/document-processing#third-party-ocr) for more information about possible error types.*
</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.
* `form` (string (uuid), optional): ID of the form.

<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": ["forms.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": ["forms.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": "forms.ocr_completed",
"name": "OCR is completed",
"data": {
"account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3",
"form": "ada143be-3c90-4534-b7ea-9899674dc6e0"
}
},
null,
2

```

<RefSubLayout.Divider />

## OCR failed

**POST** `/v1/webhooks`

<Note>
  Implement the `forms.ocr_failed` webhook to know when OCR fails for uploaded documents.

  * The `forms.ocr_failed` webhook notifies your system when data retrieval through third party OCR has failed for uploaded documents.
  * This webhook triggers when third party OCR has failed for **all** documents manually uploaded by the user using document upload. The `metadata` field of each failed document returns an `ocr_data` object with the specific [type](/legacy/guides/argyle-link/flows/document-processing#third-party-ocr) of `error`.
</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.
* `form` (string (uuid), optional): ID of the form.

<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": ["forms.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": ["forms.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": "forms.ocr_failed",
"name": "OCR has failed",
"data": {
"account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3",
"form": "4334r6e-a964-45eef6-b201-64464"
}
},
null,
2

```