Install & Compatibility
Where this runs
tested against v2.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.414s · 36.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.8s · import 1.312s · 36MB
35MB installed
● package 35MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Svix
✓ from svix.api import Svix
For the synchronous API client.
SvixAsync
✓ from svix.api import SvixAsync
For the asynchronous API client.
ApplicationIn
✓ from svix.api import ApplicationIn
Commonly used data model for creating applications.
Webhook
✓ from svix.webhooks import Webhook
For verifying incoming webhook signatures.
This quickstart demonstrates how to initialize the Svix client (both synchronous and asynchronous), create an application, and send a message. Replace `SVIX_AUTH_TOKEN` with your actual authentication token, typically obtained from the Svix dashboard.
import os
from svix.api import Svix, ApplicationIn, MessageIn
AUTH_TOKEN = os.environ.get('SVIX_AUTH_TOKEN', 'auth-token-placeholder') # Replace with your actual token or env var
async def main_async():
svix_async = SvixAsync(AUTH_TOKEN)
print("Creating application (async)...")
app = await svix_async.application.create(ApplicationIn(name="My Async App"))
print(f"Application created: {app.id}")
print("Sending message (async)...")
message = await svix_async.message.create(app.id, MessageIn(event_type="user.created", payload={'user_id': '123'}))
print(f"Message sent: {message.id}")
def main_sync():
svix_sync = Svix(AUTH_TOKEN)
print("Creating application (sync)...")
app = svix_sync.application.create(ApplicationIn(name="My Sync App"))
print(f"Application created: {app.id}")
print("Sending message (sync)...")
message = svix_sync.message.create(app.id, MessageIn(event_type="user.created", payload={'user_id': '456'}))
print(f"Message sent: {message.id}")
if __name__ == '__main__':
# Example for synchronous usage
main_sync()
# Example for asynchronous usage (requires an async event loop)
# import asyncio
# asyncio.run(main_async())
Debug
Known issues
breakingThe exception type changed when `asyncio` and type hint support were introduced in versions >=0.53.0. If you were catching specific Svix exceptions, these names may have changed.fixReview and update exception handling in your code to match the new exception types introduced with the async/typed library update.
affects: >=0.53.0
breakingAn SDK overhaul in February 2025 introduced minor breaking changes, primarily affecting option structures and parameter names. These changes were designed to be caught by static analysis or at compile/type-check time.fixConsult the official changelog for specific API changes. Update code to use new option structures or parameter names as indicated by type checkers or runtime errors.
affects: post-February 2025 releases (e.g., v1.x.x)
gotchaWebhook signature verification *must* use the raw, unparsed request body. If a framework (e.g., Flask, Django) automatically parses the request body as JSON and then stringifies it, it will invalidate the signature. Always retrieve the original bytes/string of the request body before passing it to the `Webhook.verify()` method.fixEnsure your webhook endpoint captures the raw request body (e.g., `request.get_data(as_text=True)` in Flask or `request.body` in Django) before passing it to `svix.webhooks.Webhook.verify()`.
affects: All versions
gotchaSvix libraries automatically reject webhooks with a timestamp more than five minutes from the current time to mitigate replay attacks. Your server's clock must be accurately synchronized (NTP recommended) to avoid legitimate webhooks being rejected.fixEnsure your server's system clock is synchronized using a Network Time Protocol (NTP) service to maintain accuracy.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'svix'
The Svix Python library has not been installed in the current environment.
fixInstall the library using pip: `pip install svix`
svix.WebhookVerificationError: Secret is required
The `Webhook` verification method was called without providing the webhook signing secret during initialization.
fixInitialize the `Webhook` object with your Svix webhook signing secret (e.g., `whsec_...`).
```python
from svix import Webhook
# ...
webhook_secret = "whsec_your_secret_here" # Get from environment variable or secure config
verifier = Webhook(webhook_secret)
# ...
```
svix.WebhookVerificationError: Invalid Signature
The provided `svix-signature` header does not match the signature calculated from the secret, timestamp, and payload, indicating the webhook either used an incorrect secret, was tampered with, or headers/body were malformed during verification.
fixVerify that the `webhook_secret` used to initialize `Webhook` is correct, the `svix-signature` and `svix-timestamp` headers are correctly extracted from the request, and the `body` is the raw, untampered request body that was sent by Svix.
```python
from svix import Webhook, WebhookVerificationError
# ...
webhook_secret = "whsec_your_secret_here"
verifier = Webhook(webhook_secret)
try:
payload = verifier.verify(body_from_request, headers_from_request)
# Webhook successfully verified, process payload
except WebhookVerificationError as e:
# Log and handle the verification failure
print(f"Webhook verification failed: {e}")
``` svix.http.httpx_async.HTTPError: HTTP Status Code: 400. Body: {"detail":"missing field `appId`"}
A required field, such as `appId` for creating a message or other API calls, was missing or incorrectly provided in the request payload.
fixEnsure all required parameters are provided and correctly formatted according to the Svix API documentation for the specific endpoint being called. For message creation, ensure `app_id` and `event_type_id` are included and valid.
```python
from svix import Svix
from svix.models import MessageIn
# ...
svix_client = Svix("auth_token")
app_id = "app_id_from_svix"
message_data = MessageIn(event_type_id="user.signed_up", payload={"email": "test@example.com"})
# Ensure appId is correctly passed to the create method
response = svix_client.messages.create(app_id, message_data)
print(response)
``` Upgrade
Version history
2.1.0latest on PyPI · released Aug 25, 2026
Audit
Dependencies
dataclassesoptionalRequired for Python 3.6 support; included in Python 3.7+.