Introducing the Hookbase Python SDK

Python Meets Webhooks

We have been hearing from Python developers who want first-class webhook management without leaving their language of choice. Today we are shipping hookbase v1.0.0 on PyPI, the official Python SDK for the Hookbase API.

pip install hookbase

The SDK covers every Hookbase API endpoint with full type safety via Pydantic models, both synchronous and asynchronous clients, and built-in webhook signature verification.

Quick Start

Get up and running in a few lines:

from hookbase import HookbaseClient

client = HookbaseClient(
    api_key="whr_your_api_key",
    organization_id="org_xxx"
)

# List your sources
sources = client.sources.list()
for source in sources:
    print(f"{source.name} - {source.slug}")

That is it. The client handles authentication, request serialization, error handling, and response parsing automatically.

Async Support

Building an async application with FastAPI, Starlette, or plain asyncio? Use the async client:

from hookbase import AsyncHookbaseClient

client = AsyncHookbaseClient(
    api_key="whr_your_api_key",
    organization_id="org_xxx"
)

sources = await client.sources.list()
events = await client.events.list(limit=10)

Both clients share the same interface, so switching between sync and async is a one-line change.

Full API Coverage

The SDK provides typed methods for every Hookbase resource:

Inbound Webhooks

# Create a source
source = client.sources.create(
    name="Stripe Production",
    slug="stripe-prod",
    provider="stripe"
)

# Create a destination
destination = client.destinations.create(
    name="Order Service",
    url="https://api.example.com/webhooks",
    http_method="POST"
)

# Connect them with a route
route = client.routes.create(
    name="Stripe to Orders",
    source_id=source.id,
    destination_id=destination.id
)

Outbound Webhooks

# Create an application for your customers
app = client.applications.create(
    name="My SaaS Webhooks",
    slug="my-saas"
)

# Register a customer endpoint
endpoint = client.endpoints.create(
    application_id=app.id,
    url="https://customer.example.com/webhooks"
)

# Send an event
client.messages.create(
    application_id=app.id,
    event_type="order.created",
    payload={"order_id": "ord_123", "total": 49.99}
)

Cron Jobs

# Schedule a recurring job
job = client.cron_jobs.create(
    name="Hourly Sync",
    schedule="0 * * * *",
    destination_id=destination.id,
    payload={"action": "sync"}
)

# Trigger manually
client.cron_jobs.trigger(job.id)

Pagination

List endpoints return paginated results. Iterate through pages easily:

# Get first page
events = client.events.list(limit=50)

# Get next page using cursor
next_page = client.events.list(limit=50, cursor=events[-1].id)

Webhook Verification

When receiving webhooks from Hookbase, verify the signature to ensure authenticity:

from hookbase import verify_webhook

payload = request.body
signature = request.headers["x-hookbase-signature"]
timestamp = request.headers["x-hookbase-timestamp"]

try:
    event = verify_webhook(
        payload=payload,
        signature=signature,
        timestamp=timestamp,
        secret="whsec_your_signing_secret"
    )
    # Process verified event
    print(f"Verified event: {event['type']}")
except Exception as e:
    print(f"Verification failed: {e}")

The verification function checks both the HMAC signature and the timestamp to prevent replay attacks.

Error Handling

The SDK raises typed exceptions so you can handle errors precisely:

from hookbase.exceptions import (
    AuthenticationError,
    NotFoundError,
    RateLimitError,
    ValidationError,
    HookbaseError
)

try:
    source = client.sources.get("nonexistent")
except NotFoundError:
    print("Source not found")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except AuthenticationError:
    print("Invalid API key")
except HookbaseError as e:
    print(f"API error: {e.status_code} - {e.message}")

Pydantic Models

Every API response is deserialized into a Pydantic model with full type hints. Your IDE gets autocomplete, your linter catches errors, and your code is self-documenting:

source = client.sources.get("src_xxx")

# Full type safety
print(source.id)           # str
print(source.name)         # str
print(source.provider)     # str
print(source.created_at)   # datetime
print(source.is_active)    # bool

Requirements

• Python 3.8+
• No required dependencies beyond httpx and pydantic

Get Started

Install the SDK and create your first webhook route in under a minute:

pip install hookbase

Check out the full documentation and source code:

• PyPI: pypi.org/project/hookbase
• GitHub: github.com/hookbase/hookbase-python
• Docs: docs.hookbase.app/sdks/python

What is Next

This is v1.0.0, and we are already working on what comes next:

• Webhook event type filtering for more granular subscriptions
• Retry configuration per client instance
• CLI integration for managing resources from the terminal
• Django and FastAPI middleware for easy webhook receiving

We would love your feedback. Open an issue on GitHub or reach out at [email protected].

---

The Hookbase Python SDK is open source and available now on PyPI. Install it with pip install hookbase and start managing webhooks from Python today.