SEC 09 / REFERENCE

Deeper reference

Material you won’t need on a first pass, kept for completeness.

Webhooks

ElevenLabs signs webhook payloads with an ElevenLabs-Signature header, and the SDK ships helpers that validate the HMAC signature and timestamp before the event is ever parsed, as documented in the webhooks reference. Verification generally requires access to the original raw request body — parsing and reserializing the JSON first can invalidate the signature, so the raw payload needs to reach the verifier before any JSON-parsing middleware touches it.

Retries are not universally enabled. The same webhooks reference says retries are disabled by default, with limited retry support for post-call transcription events and a finite retry count. Treat delivery as at-least-once only where the documentation says so, and design for at-most-once — or zero — everywhere else.

A webhook handler should, in order:

1. Verify the signature.
2. Store an event identifier or payload hash.
3. Acknowledge quickly.
4. Process asynchronously.
5. Be idempotent.
6. Reconcile missed events with the REST API where possible.

Zero-retention mode

ElevenLabs documents a Zero Retention Mode for eligible enterprise use cases, covered in the zero-retention mode reference. Depending on product and configuration, requests can set enable_logging=false, or an agent can be configured for reduced retention. With zero retention, generated items do not appear in normal history, which also reduces the information available for your own debugging and support. Not every product is eligible: the documented eligibility table excludes areas such as music, dubbing, and voice cloning.

Zero retention at the vendor does not stop your own application, reverse proxy, observability platform, or error tracker from recording sensitive content anyway. A production privacy design should separately decide:

• what ElevenLabs retains;
• what your application retains;
• whether transcripts are logged;
• whether raw audio is stored;
• whether prompts and agent tool results enter analytics;
• whether support engineers can access production content;
• how users request deletion;
• how voice-cloning consent and authorization are recorded.

Versioning & upgrade strategy

The Python package’s release history shows a frequent cadence, often with regenerated clients. The 2.60.0 Python release, for example, included an asynchronous Conversation startup fix alongside generated-client updates, and the corresponding JavaScript release was also an SDK regeneration — visible directly in the package’s release history on PyPI.

A sensible upgrade policy:

1. Pin exact versions in applications that handle live audio.
2. Let automated tooling open upgrade pull requests rather than merging them.
3. Run contract tests against representative TTS, STT, voice, and agent operations.
4. Test WebRTC start, stop, reconnect, and device release on actual devices.
5. Compare generated TypeScript/Python type changes.
6. Review release notes and the breaking-change policy.
7. Deploy to a small traffic segment before broad rollout.

For JSON stored in your own database, retain the raw response alongside normalized fields where permitted. This helps investigate behaviour after generated types evolve.

The full decision guide

References

• Webhooks reference
• Zero-retention mode reference
• Breaking-changes policy
• elevenlabs package on PyPI