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

# Webhook Integration Guide

> Configure inbound/outbound webhook integrations with verification, retries, and idempotency.

## Audience

* Developers integrating event streams with external systems
* Admins/support teams operating webhook endpoints

## Prerequisites

* Public HTTPS endpoint
* Workspace webhook secret from Developer Tools
* Ability to persist event IDs for idempotency

## Webhook event categories

* Call lifecycle events (status, completion, outcomes)
* Messaging events (for supported inbound SMS flows)
* Billing/identity/provider lifecycle events where applicable to your integration path

## Inbound vs outbound expectations

### Outbound (Voqo -> your endpoint)

* Voqo sends POST requests to your configured URL.
* Your endpoint should verify signatures and return `2xx` quickly.
* Non-`2xx` responses may be retried.

### Inbound (provider -> Voqo)

* Provider webhooks update user-visible state (for example call/billing/messaging outcomes).
* Delays or failures can affect state freshness in app surfaces.

## Signature verification

Use your webhook secret to verify message authenticity.

Recommended checks:

* Validate signature header
* Validate timestamp freshness
* Reject missing/invalid signatures

## Retry behavior

* Design for at-least-once delivery semantics.
* Return `2xx` only after successful persistence.
* For transient failures, rely on retry and keep handlers idempotent.

## Idempotency guidance

* Persist processed event IDs.
* Ignore duplicates safely.
* Make handlers side-effect safe when replayed.

## Minimal handler expectations

1. Parse payload and required headers.
2. Verify signature + timestamp.
3. Check idempotency store for prior processing.
4. Process business logic.
5. Return `200` once processing is durable.

## Troubleshooting

### Signature verification failing

* Confirm latest secret is used (not rotated one).
* Confirm request body is verified before mutation.
* Check timestamp skew tolerance.

### Duplicate events causing duplicate side effects

* Add event ID dedupe store.
* Make writes idempotent by unique event key.

### Webhook appears delayed

* Confirm endpoint latency and `2xx` responses.
* Check retry backlog and transient provider failures.

If unresolved, contact [support@voqo.ai](mailto:support@voqo.ai) with workspace ID, webhook endpoint URL (redacted), event ID, and timestamps.

## Related docs

* [Manage API Keys and Secrets](../developer-tools/manage-api-keys-and-secrets)
* [API Reference](/api-reference/introduction)
* [Public Recording and SMS Replies API](/api-reference/public-recording-and-sms-replies)