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

# Integrations, inbound email, and webhooks

> Connect external systems, control inbound email senders, and deliver Vida events reliably.

Use the narrowest integration surface that matches the job:

| Need                                                                                  | Use                                             |
| ------------------------------------------------------------------------------------- | ----------------------------------------------- |
| Install a supported app on an Agent                                                   | Apps API, followed by Agent staging and publish |
| Store configuration for a supported legacy integration                                | Integrations API                                |
| Receive Vida lifecycle events                                                         | Webhooks API                                    |
| Forward an inbound provider webhook through your application before Vida processes it | Webhook Relay API                               |
| Let approved senders create inbound email work for an Agent                           | Inbound Email API                               |

Do not treat webhook relays and event webhooks as interchangeable. A relay is an inbound delivery path; an event webhook is an outbound notification from Vida.

## Configure inbound email

Inbound email policy belongs to the selected Agent account:

1. Read `GET /api/v2/email/inboundPolicy?targetAccountId=...`.
2. Choose `allowlist` for controlled senders or `open` when any sender should be accepted.
3. Add approved addresses through `POST /api/v2/email/inboundWhitelist` before enabling allowlist mode.
4. Update the policy with `PUT /api/v2/email/inboundPolicy`.
5. Re-read both policy and allowlist, then send a representative email from an authorized address.

Removing an address affects delivery only while the policy is `allowlist`. Confirm the exact address and re-read the list after removal.

## Deliver Vida events to your system

The Webhooks API supports `conversation`, `incoming`, `contact`, `agent`, and `onboarding` event types. Create a separate destination when different systems own different event categories.

Vida sends JSON with these verification headers:

* `X-Vida-Event`
* `X-Vida-Timestamp`
* `X-Vida-Signature-Version`
* `X-Vida-Signature`

Respond quickly with a successful status and process longer work asynchronously. Deduplicate deliveries using stable identifiers in the payload when available. A destination that returns HTTP `410 Gone` may be removed automatically, so use `410` only when the endpoint is permanently retired.

Read the webhook list after creation or deletion. Use a representative event to verify both delivery and your handler's account attribution before relying on it in production.

## Configure an inbound webhook relay

1. List supported relay types with `GET /api/v2/webhookRelay/types`.
2. Read the current configuration for the selected type.
3. Create or update only a supported type with an HTTPS destination you control.
4. Re-read it and send a safe provider test event.

Deleting a relay stops that forwarding path. Confirm the provider's direct Vida delivery path or replacement integration before deleting it.

## Install apps safely

Read the App catalog and selected App detail first. Install or update the App for the Agent account, resolve its declared requirements, then add the exact App identifier to Agent staging. Re-read staging, test the capability, publish with explicit approval, and verify live configuration.

Store credentials through the setup flow documented by the selected App or Computer Agent skill. Agent instructions and Task context are for work guidance, not credential configuration.