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

# Events and notifications

> What events Documate sends, when they fire, and where you turn them on.

Documate can notify your systems and your team when a file is accepted or a document finishes. You choose **which events** to send and **where** they go: webhook, email, or in-app.

## Where you set this up

### Business defaults

Open **Business → Integrations & events**.

<Tabs>
  <Tab title="Webhook">
    1. Turn **Enabled** on.
    2. Enter the HTTPS URL Documate should POST to.
    3. Optionally set a shared secret (used to sign the POST).
    4. Tick the events you want on the webhook.
    5. Save.
  </Tab>

  <Tab title="Email notify">
    1. Turn **Enabled** on.
    2. Enter recipient addresses (comma-separated). These are your team, not Documate support.
    3. Tick the events that should send email.
    4. Save.
  </Tab>

  <Tab title="In-app notify">
    1. Turn **Enabled** on.
    2. Tick the events that should appear in the app.
    3. Save.
  </Tab>
</Tabs>

Use **Webhook deliveries** on the same page to review recent POSTs.

### Channel override

Open **Channels & intake → Intake**.

* Leave **Inherit Business defaults** on to use the business webhook URL, secret, and event ticks.
* Uncheck inherit to set a different URL, secret, and event list for **this channel only**. Email and in-app still follow the business settings.

<Note>
  Live delivery uses the **effective** channel webhook config (inherited or overridden).
</Note>

## How events are sent

When a subscribed event happens, Documate does the following for each **enabled** destination that has that event ticked:

| Destination | What Documate does |
| - | - |
| **Webhook** | HTTPS **POST** JSON to your URL. Headers include `X-Documate-Event` (the wire key) and, if you set a secret, `X-Documate-Signature`. |
| **Email** | Sends a notification to the recipients you listed. |
| **In-app** | Shows a notification in the Documate app. |

Nothing is sent if that destination is off, or if the event is not ticked.

Events are **not** sent when:

* You use [sync extract](/guides/sync-extract) (`api_sync`).
* You only poll the partner API. Polling does not create events.
* The file or document never reaches that state (for example a document that stays Processing).

## Available events

The app shows Title Case labels. Webhooks use the **dotted key**.

| In the app | Wire key | When it is sent |
| - | - | - |
| File received | `file.received` | As soon as a file is accepted (app upload, API upload, or email intake). Processing has not finished. |
| File completed | `file.completed` | When **every** document on that file is Ready. Not sent if any document failed or was cancelled. |
| Document ready | `document.ready` | When one document finishes extraction successfully. A mixed file can send this more than once. |
| Document failed | `document.failed` | When one document fails (for example it could not be identified, or extraction failed). |
| Document cancelled | `document.cancelled` | When you cancel that document. |

<Tip>
  Typical partner setup: tick **File received** (to fetch the original file) plus **Document ready** and **Document failed** (to ingest or alert). Add **File completed** if you only want a signal when the whole pack succeeded.
</Tip>

## Test a webhook

On **Business → Integrations & events**, use **Test** next to the webhook URL. Documate posts a sample payload for a recent file or document.

* Test POSTs include `X-Documate-Test: true`.
* Signing still uses your secret when one is configured. Verify `X-Documate-Signature`; do not treat the test header as authentication.
* Test prefers the **business** secret you just saved. Live traffic still uses the effective channel config.

## Payload and verification

Webhooks never include raw file bytes. You get IDs and optional short-lived download URLs.

See [Webhooks](/guides/webhooks) for the JSON shape, headers, and how to download the original file after `file.received`. See [API webhooks](/api-reference/webhooks) for signature samples.

## Related

* [Integrations](/guides/integrations)
* [Identify document types](/guides/classification)
* [Channels and intake](/guides/channels)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.