Skip to main content
Use the narrowest integration surface that matches the job: 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. The policy is checked before Vida delivers a message to the Agent, creates its inbound email event, or starts Agent work. If a workflow expects the Agent to reply when someone emails it, configure that sender before testing. All inbound messages must pass standard email authentication checks, including DKIM alignment. After that check, allowlist accepts only exact addresses on the Agent’s list, while open accepts any sender.
  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.
An unlisted sender in allowlist mode does not produce an inbound message or email.received event, so an event-driven reply workflow cannot run. The allowlist controls inbound acceptance only; it does not restrict recipients of a new outbound email or a reply to a message Vida already accepted. 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.