Skip to main content

Hookbase Python SDK

The official Python SDK for the Hookbase webhook management platform.

Installation

pip install hookbase

Quick Start

from hookbase import Hookbase

client = Hookbase(api_key="whr_your_api_key")

# List webhook sources
sources = client.sources.list()
for source in sources.data:
    print(f"{source.name} ({source.provider})")

# Send an outbound webhook
result = client.outbound.messages.send(
    "app_123",
    event_type="order.created",
    payload={"orderId": "456", "amount": 99.99},
)
print(f"Sent: {result.event_id}")

Async Support

from hookbase import AsyncHookbase

async with AsyncHookbase(api_key="whr_...") as client:
    sources = await client.sources.list()

API Reference

Client Initialization

from hookbase import Hookbase

client = Hookbase(
    api_key="whr_...",           # Required
    base_url="https://...",      # Default: https://api.hookbase.app
    timeout=30.0,                # Seconds (default: 30)
    max_retries=3,               # Default: 3
    debug=False,                 # Log requests
)

Inbound Webhooks

# Sources
client.sources.list(search="github", provider="github")
client.sources.create({"name": "GitHub", "slug": "github", "provider": "github"})
client.sources.get("src_id")
client.sources.update("src_id", {"name": "Updated"})
client.sources.delete("src_id")
client.sources.rotate_secret("src_id")  # 400 for vendor-issued/public-key/built-in secrets
client.sources.reveal_secret("src_id")

# A provider that verifies with no secret: signing_secret comes back None
wise = client.sources.create({"name": "Wise", "slug": "wise", "provider": "wise"})
assert wise.verifies_without_secret and wise.signing_secret is None

# WhatsApp (Meta) sources also carry a verify token
wa = client.sources.create({"name": "WhatsApp", "slug": "whatsapp", "provider": "whatsapp"})
print(wa.verify_token)
client.sources.rotate_verify_token(wa.id)

# Notion parks its verification token until you adopt it
pending = client.sources.get_pending_verification("notion")
client.sources.adopt_pending_verification("notion")

# Provider catalog: which secret each provider needs (public, no auth needed)
for p in client.providers.list(category="payments").providers:
    print(p.hookbase_provider, p.signature_verification and p.signature_verification.secret_source)
client.providers.get("stripe").signature_verification

# Destinations
client.destinations.list()
client.destinations.create({"name": "Backend", "url": "https://..."})
client.destinations.test("dst_id")

# Routes
client.routes.create({"name": "Route", "sourceId": "src_id", "destinationId": "dst_id"})
client.routes.get_circuit_status("route_id")
client.routes.reset_circuit("route_id")

# Events & Deliveries
client.events.list(source_id="src_id", from_date="2024-01-01")  # id or slug; unknown -> 404
client.events.get("evt_id")  # Includes payload and deliveries
client.deliveries.replay("del_id")
client.deliveries.bulk_replay(["del_1", "del_2"])

# Transforms & Filters
client.transforms.create({"name": "Extract", "transformType": "jsonata", "code": "$.data"})
client.transforms.test("txf_id", payload={"data": {"key": "value"}})
client.filters.test([{"field": "$.type", "operator": "eq", "value": "order"}], payload={...})

# Schemas
client.schemas.create({"name": "OrderSchema", "jsonSchema": {"type": "object", ...}})

Outbound Webhooks

# Applications
client.outbound.applications.create({"name": "Acme", "externalId": "cust_123"})
client.outbound.applications.get_by_external_id("cust_123")

# Endpoints
client.outbound.endpoints.create("app_id", {"url": "https://..."})
client.outbound.endpoints.rotate_secret("ep_id", grace_period=3600)

# An unset field is left alone by an update, so `None` cannot also mean "reset
# this". Name the setting in `clear` to send an explicit null for it:
client.outbound.endpoints.update("ep_id", {"clear": ["retryDelays"]})

# Event Types & Subscriptions
client.outbound.event_types.create({"name": "order.created", "category": "orders"})
client.outbound.subscriptions.create({"endpointId": "ep_id", "eventTypeId": "et_id"})
client.outbound.subscriptions.bulk_create("ep_id", ["et_1", "et_2"])

# Send Events
client.outbound.messages.send("app_id", event_type="order.created", payload={...})

# Message Log
client.outbound.message_log.list(application_id="app_id")
client.outbound.message_log.list_attempts("msg_id")
client.outbound.message_log.stats()

# Dead Letter Queue
client.outbound.dlq.list()
client.outbound.dlq.stats()
client.outbound.dlq.retry("dlq_id")
client.outbound.dlq.retry_bulk(["dlq_1", "dlq_2"])

Admin

# Organizations
client.organizations.list()
client.organizations.list_members("org_id")
client.organizations.invite("org_id", "user@example.com", "member")

# API Keys
client.api_keys.create({"name": "CI Key", "scopes": ["read", "write"]})

# Analytics
client.analytics.dashboard(range="30d")

# Cron Jobs & Tunnels
client.cron_jobs.list()
client.tunnels.list()

Pagination

# Offset-based (sources, destinations, routes, etc.)
page = client.sources.list(page_size=10)
print(f"Total: {page.total}, Page: {page.page}")

# Auto-paginate through all items
for source in page.auto_paging_iter():
    print(source.name)

# Manual pagination
while page.has_more:
    page = page.next_page()

# Cursor-based (applications, endpoints, subscriptions, etc.)
page = client.outbound.applications.list(limit=50)
for app in page.auto_paging_iter():
    print(app.name)

Webhook Verification

from hookbase import Webhook, WebhookVerificationError

wh = Webhook("whsec_your_secret")

try:
    payload = wh.verify(request_body, request_headers)
    print(f"Verified: {payload}")
except WebhookVerificationError as e:
    print(f"Invalid: {e}")

# Generate test headers
headers = wh.generate_test_headers('{"test": true}')

Error Handling

from hookbase import (
    HookbaseError,          # Base error
    APIError,               # API returned an error
    AuthenticationError,    # 401
    ForbiddenError,         # 403
    NotFoundError,          # 404
    ValidationError,        # 400/422
    ConflictError,          # 409
    RateLimitError,         # 429 (has retry_after)
    TimeoutError,           # Request timed out
    NetworkError,           # Connection failed
    WebhookVerificationError,
)

try:
    client.sources.get("src_id")
except NotFoundError:
    print("Not found")
except RateLimitError as e:
    print(f"Retry after {e.retry_after}s")
except APIError as e:
    print(f"{e.status_code}: {e} (request_id={e.request_id})")

Pydantic Models

All responses are typed Pydantic models with camelCase alias support:

from hookbase.models import Source, CreateSourceParams

# Use Pydantic models for type safety
params = CreateSourceParams(name="GitHub", slug="github", provider="github")
source = client.sources.create(params)

# Or use plain dicts
source = client.sources.create({"name": "GitHub", "slug": "github", "provider": "github"})

# `provider` is any string (hookbase.models.KNOWN_SOURCE_PROVIDERS lists today's values), so a
# source with a provider newer than this package still parses.

Development

pip install -e ".[dev]"
pytest tests/ -v
mypy src/hookbase
ruff check src/ tests/

License

MIT

Metadata

Release files for hookbase 3.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hookbase 3.2.0
File Size Uploaded Provenance Actions
hookbase-3.2.0.tar.gz 66.7 kB With provenance Details for hookbase-3.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hookbase 3.2.0
File Interpreter ABI Platform Actions
hookbase-3.2.0-py3-none-any.whl Python 3 none any Details for hookbase-3.2.0-py3-none-any.whl

Total release size: 134.3 kB

Release files / hookbase-3.2.0.tar.gz

Download URL hookbase-3.2.0.tar.gz
Size 66.7 kB
Tags Source
SHA-256 checksum
How to use checksums
ec29d2e9fcfb10d52ddfb0c4ec452c99ac5064ddc0fcaf2afe07590ce63ac508
BLAKE2b-256 checksum
How to use checksums
81ba2643a3f1068007f7e20d05d6bf1626405bcbe46977f18d12f7a7567f9262
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.

Transparency log

Release files / hookbase-3.2.0-py3-none-any.whl

Download URL hookbase-3.2.0-py3-none-any.whl
Size 67.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4d89502061b50fff6b56b00e3f20a60e3678029a2da07661975ad413b1e84f60
BLAKE2b-256 checksum
How to use checksums
e9ae6c1f7392b6888e9b3df0cd2434f0354709e457d4e52dcbd69adc525764e9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.

Transparency log

Security for hookbase 3.2.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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for hookbase-3.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.

Transparency log

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page