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

# Events

> The events Deck sends a webhook for and example payloads.

### Explanation of terms

| Output Field    | Description                               |
| --------------- | ----------------------------------------- |
| `job_guid`      | Unique identifier for the job             |
| `environment`   | Environment in which the action was made  |
| `message`       | Instructions or explanations for the user |
| `webhook_code`  | Same as JobCode                           |
| `webhook_type`  | Category of webhook                       |
| `error_code`    | Code of the error                         |
| `error_message` | Message related to the error              |

***

## EnsureConnection

### Connection Successful

Fired when EnsureConnection has completed.

```json theme={null}
{
  "job_guid": "55bba4ec-7242-4f52-b3c0-08de128283fc",
  "output": {
    "access_token": "access-development-2b566e6a-d404-4099-9cf4-08de1282be2b"
  },
  "webhook_type": "Job",
  "webhook_code": "EnsureConnection",
  "environment": "Production"
}
```

**Suggested action:** Securely store the access token. You can now call jobs for these credentials.

***

### Error

Fired when EnsureConnection fails unexpectedly.

```json theme={null}
{
  "job_guid": "55bba4ec-7242-4f52-b3c0-08de128283fc",
  "error": { 
    "error_code": "Unexpected", 
    "error_message": "" 
  },
  "webhook_type": "Job",
  "webhook_code": "EnsureConnection",
  "environment": "Production"
}
```

**Suggested action:** Wait a moment and try again.

***

### Invalid Credentials

Fired when EnsureConnection fails due to erroneous credentials.

```json theme={null}
{
  "job_guid": "8b7f2b93-3100-4415-b3c3-08de128283fc",
  "error": {
    "error_code": "InvalidCredentials",
    "error_message": "Invalid Credentials"
  },
  "webhook_type": "Job",
  "webhook_code": "EnsureConnection",
  "environment": "Production"
}
```

**Suggested action:** Prompt the user to enter the correct credentials.

***

### MFA Required

Fired when an MFA code is required during sign-in.

```json theme={null}
{
  "job_guid": "1c7d53bf-df62-4864-39fd-08de127ffd4a",
  "question": "We just sent a code to your email. Enter it to confirm your identity and turn on two-step verification.",
  "method_selected": "email",
  "answer_expected_digits": 6,
  "webhook_type": "Job",
  "webhook_code": "MfaRequired",
  "environment": "Production"
}
```

**Suggested action:** Call the [`jobs/mfa/answer`](https://docs.deck.co/api-reference-v1/connections/respond-to-mfa-request) endpoint with your answer.

***

### Invalid Answer to the MFA Question

Fired when the MFA code provided is invalid.

```json theme={null}
 {
   "job_guid": "45311d68-5092-4fe8-635b-08de14ef0c19",
   "error": { 
      "error_code": "MfaCodeInvalid", 
      "error_message": "Invalid mfa" 
   },
   "webhook_type": "Job",
   "webhook_code": "EnsureConnection",
   "environment": "Production"
 }
```

**Suggested action:** Prompt the user again for their MFA code.

***

## Jobs

### Successful Job

Fired when a job completed successfully.

```json theme={null}
{
  "job_guid": "b35aa2af-41e4-4833-95c9-9efd2069e70c",
  "output": {
    "success": true,
    Rest of payload
  },
  "webhook_type": "Job",
  "webhook_code": "JobCode",
  "environment": "Production"
}
```

**Suggested action:** Call your next job or CloseConnection to finish the flow.

***

### Unsuccessful Job

Fired when a job did not complete successfully.

```json theme={null}
{
  "job_guid": "b35aa2af-41e4-4833-95c9-9efd2069e70c",
  "output": {
    "success": false,
    "message": "Invalid inputs."
  },
  "webhook_type": "Job",
  "webhook_code": "JobCode",
  "environment": "Production"
}
```

**Suggested action:** Follow the message's prompt to fix the error.

***

## Documents

### Document Created

Fired when a document is fetched and stored on our server.

```json theme={null}
 {
   "job_guid": "30fe6fad-52c2-490e-f57b-08de15d052be",
   "document_id": "864ce2ed-78ce-4c5d-f4dc-08de1658e265",
   "webhook_type": "Document",
   "webhook_code": "DocumentCreated",
   "environment": "Production"
 }
```

**Suggested action:** Call the [`/jobs/documents/{documentId}`](https://docs.deck.co/api-reference-v1/storage/download-a-document) endpoint to retrieve your document(s).

***

### Successful Data Extraction

Fired when data has been successfully extracted from a document.

```json theme={null}
{
  "webhook_type": "Document",
  "webhook_code": "DocumentExtractionSuccess",
  "environment": "Production",
  "job_guid": "65e038fd-3fdc-4f45-3029-08de33819524",
  "document_id": "15e038fd-3fdc-4f45-3029-08de33819525",
  "document_extraction_id": "65e038fd-3fdc-4f45-3029-08de33819524"
}
```

**Suggested action:** Call the [`/jobs/documents/{documentId}`](https://docs.deck.co/api-reference-v1/storage/download-a-document) endpoint with the `document_id` to retrieve your raw document(s) or with the `document_extraction_id` to retrieve the extraction file.

***

### Failed Data Extraction

Fired when data could not be successfully extracted from a document.

```json theme={null}
{
  "webhook_type": "Document",
  "webhook_code": "DocumentExtractionFailed",
  "environment": "Production",
  "job_guid": "65e038fd-3fdc-4f45-3029-08de33819524",
  "document_id": "15e038fd-3fdc-4f45-3029-08de33819525",
}
```

**Suggested action:** Call the [`/jobs/documents/{documentId}`](https://docs.deck.co/api-reference-v1/storage/download-a-document) endpoint with the `document_id` to retrieve your raw document(s) or retry extracting the data.

***

### URL webhook

Fired when a document is ready to be fetched.
It is essentially a Successful Job webhook that contains the URL to download your document(s).

```json theme={null}
 {
  "job_guid": "b35aa2af-41e4-4833-95c9-9efd2069e70c",
  "output": {
    "success": true,
    "message": "",
    "document_list_url": "https://live.deck.co/api/v1/jobs/b35aa2af-41e4-4833-95c9-9efd2069e70c/documents",														//Where you can download your documents
  },
  "webhook_type": "Job",
  "webhook_code": "FetchTrialBalance",
  "environment": "Production"
 }
```

**Suggested action:** Call the [`/jobs/{jobGuid}/documents`](https://docs.deck.co/api-reference-v1/storage/list-documents) endpoint to get a list of documents related to the job that fetched them.