Volley Python SDK
Official Python SDK for the Volley API. This SDK provides a convenient way to interact with the Volley webhook infrastructure API.
Volley is a webhook infrastructure platform that provides reliable webhook delivery, rate limiting, retries, monitoring, and more.
Resources
- Documentation: https://docs.volleyhooks.com
- Getting Started Guide: https://docs.volleyhooks.com/getting-started
- API Reference: https://docs.volleyhooks.com/api
- Authentication Guide: https://docs.volleyhooks.com/authentication
- Security Guide: https://docs.volleyhooks.com/security
- Console: https://app.volleyhooks.com
- Website: https://volleyhooks.com
Installation
pip install volley-python
or with poetry:
poetry add volley-python
Quick Start
from volley import VolleyClient
# Create a client with your API token
client = VolleyClient("your-api-token")
# Optionally set organization context
client.set_organization_id(123)
# List organizations
orgs = client.organizations.list()
for org in orgs:
print(f"Organization: {org.name} (ID: {org.id})")
Authentication
Volley uses API tokens for authentication. These are long-lived tokens designed for programmatic access.
Getting Your API Token
- Log in to the Volley Console
- Navigate to Settings → Account → API Token
- Click View Token (you may need to verify your password)
- Copy the token and store it securely
Important: API tokens are non-expiring and provide full access to your account. Keep them secure and rotate them if compromised. See the Security Guide for best practices.
client = VolleyClient("your-api-token")
For more details on authentication, API tokens, and security, see the Authentication Guide and Security Guide.
Organization Context
When you have multiple organizations, you need to specify which organization context to use for API requests. The API verifies that resources (like projects) belong to the specified organization.
You can set the organization context in two ways:
# Method 1: Set organization ID for all subsequent requests
client.set_organization_id(123)
# Method 2: Create client with organization ID
client = VolleyClient("your-api-token", organization_id=123)
# Clear organization context (uses first accessible organization)
client.clear_organization_id()
Note: If you don't set an organization ID, the API uses your first accessible organization by default. For more details, see the API Reference - Organization Context.
Examples
Organizations
from volley import VolleyClient
from volley.models import CreateOrganizationRequest
# List all organizations
orgs = client.organizations.list()
# Get current organization
org = client.organizations.get() # None = use default
# Create organization
new_org = client.organizations.create(
CreateOrganizationRequest(name="My Organization")
)
Projects
from volley.models import CreateProjectRequest, UpdateProjectRequest
# List projects
projects = client.projects.list()
# Create project
project = client.projects.create(
CreateProjectRequest(name="My Project")
)
# Update project
updated = client.projects.update(
project.id,
UpdateProjectRequest(name="Updated Name")
)
# Delete project
client.projects.delete(project.id)
Sources
from volley.models import CreateSourceRequest, UpdateSourceRequest
# List sources in a project
sources = client.sources.list(project_id)
# Create source
source = client.sources.create(
project_id,
CreateSourceRequest(
slug="stripe-webhooks",
type="stripe",
eps=10,
auth_type="none"
)
)
# Get source details
source = client.sources.get(project_id, source_id)
# Update source
updated = client.sources.update(
project_id,
source_id,
UpdateSourceRequest(
slug="updated-slug",
eps=20
)
)
# Delete source
client.sources.delete(project_id, source_id)
Destinations
from volley.models import CreateDestinationRequest, UpdateDestinationRequest
# List destinations
destinations = client.destinations.list(project_id)
# Create destination
dest = client.destinations.create(
project_id,
CreateDestinationRequest(
name="Production Endpoint",
url="https://api.example.com/webhooks",
eps=5
)
)
# Get destination
dest = client.destinations.get(project_id, destination_id)
# Update destination
updated = client.destinations.update(
project_id,
destination_id,
UpdateDestinationRequest(
name="Updated Name",
eps=10
)
)
# Delete destination
client.destinations.delete(project_id, destination_id)
Connections
from volley.models import CreateConnectionRequest, UpdateConnectionRequest
# Create connection
conn = client.connections.create(
project_id,
CreateConnectionRequest(
source_id=source_id,
destination_id=dest_id,
status="enabled",
eps=5,
max_retries=3
)
)
# Get connection
conn = client.connections.get(project_id, connection_id)
# Update connection
updated = client.connections.update(
project_id,
connection_id,
UpdateConnectionRequest(
status="paused",
eps=10
)
)
# Delete connection
client.connections.delete(project_id, connection_id)
Events
from volley.models import ReplayEventRequest
# List events with filters
events_response = client.events.list(
project_id,
source_id=source_id,
status="failed",
limit=50,
offset=0
)
# Get event details
event = client.events.get(request_id)
# Replay failed event
result = client.events.replay(
ReplayEventRequest(event_id="evt_abc123def456")
)
Delivery Attempts
# List delivery attempts with filters
attempts_response = client.delivery_attempts.list(
project_id,
event_id="evt_abc123def456",
connection_id=connection_id,
status="failed",
limit=50,
offset=0
)
Webhooks
from volley.models import SendWebhookRequest
# Send a webhook
result = client.webhooks.send(
SendWebhookRequest(
source_id=source_id,
destination_id=destination_id,
body={"event": "test", "data": "example"},
headers={"X-Custom-Header": "value"}
)
)
Error Handling
The SDK throws VolleyException for API errors:
from volley import VolleyClient, VolleyException
try:
org = client.organizations.get(org_id)
except VolleyException as e:
if e.is_unauthorized():
print("Authentication failed")
elif e.is_forbidden():
print("Access denied")
elif e.is_not_found():
print("Resource not found")
elif e.is_rate_limited():
print("Rate limit exceeded")
else:
print(f"Error: {e.message} (Status: {e.status_code})")
Client Options
You can customize the client with various options:
import requests
# Custom base URL
client = VolleyClient(
"your-api-token",
base_url="https://api-staging.volleyhooks.com"
)
# Custom timeout
client = VolleyClient(
"your-api-token",
timeout=60 # 60 seconds
)
# Custom session with retry strategy
session = requests.Session()
client = VolleyClient(
"your-api-token",
session=session
)
Requirements
- Python 3.8 or higher
- requests >= 2.31.0
Development
Setup
# Clone the repository
git clone https://github.com/volleyhq/volley-python.git
cd volley-python
# Install in development mode
pip install -e ".[dev]"
Running Tests
# Run all tests
pytest
# Run with coverage
pytest --cov=volley --cov-report=html
# Run integration tests (requires VOLLEY_API_TOKEN)
VOLLEY_API_TOKEN=your-token pytest tests/test_integration.py
Code Formatting
# Format code
black volley tests examples
# Check formatting
black --check volley tests examples
License
MIT License - See LICENSE file for details.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Built with ❤️ by the Volley team
Metadata
Release files for volley-python 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| volley_python-1.0.0.tar.gz | 16.5 kB | Without provenance | Details for volley_python-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| volley_python-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for volley_python-1.0.0-py3-none-any.whl |
Total release size: 35.4 kB
Release files / volley_python-1.0.0.tar.gz
| Download URL | volley_python-1.0.0.tar.gz |
|---|---|
| Size | 16.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
49f709ab729bb2648ce9856b7742af1da875406df936a803b7f226a087b323ac
|
|
BLAKE2b-256 checksum How to use checksums |
389964f3b04eb58e589d6dc28e0c51b2d0a44a981c08b2f3627b0cd3b75f4aca
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Release files / volley_python-1.0.0-py3-none-any.whl
| Download URL | volley_python-1.0.0-py3-none-any.whl |
|---|---|
| Size | 18.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ab79dc65387aa936ec0efb89bb8c34182024d796598ebf83f5c794b8d5876c57
|
|
BLAKE2b-256 checksum How to use checksums |
cb8165427475f8fad1e8bd62ca969621c55ce838fe7e3ced80898dec26a4ba32
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Security for volley-python 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.