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
2xxquickly. - Non-
2xxresponses 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
2xxonly 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
- Parse payload and required headers.
- Verify signature + timestamp.
- Check idempotency store for prior processing.
- Process business logic.
- Return
200once 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
2xxresponses. - Check retry backlog and transient provider failures.