Svix Python Library

1.90.0 · active · verified Fri Apr 10

The Svix Python library provides a robust client for interacting with the Svix webhooks API, enabling developers to send, receive, and verify webhooks. It abstracts away complexities like retries, scaling, and security, offering both synchronous and asynchronous interfaces. The library supports Python 3.6+ and includes PEP 484 type hints. Svix aims to simplify webhook infrastructure, allowing applications to integrate webhook capabilities rapidly. It is actively maintained with regular updates.

Warnings

breaking The 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.
Fix: Review and update exception handling in your code to match the new exception types introduced with the async/typed library update.
breaking An 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.
Fix: Consult 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.
gotcha Webhook 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.
Fix: Ensure 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()`.
gotcha Svix 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.
Fix: Ensure your server's system clock is synchronized using a Network Time Protocol (NTP) service to maintain accuracy.

Install

pip install svix Install stable version

Imports

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.

Quickstart

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())

view raw JSON →