Skip to main content

Hookbase Python SDK

The official Python SDK for the Hookbase webhook management platform.

Installation

pip install hookbase
# To verify Ed25519 (v1a) signed webhooks, include the optional extra:
pip install 'hookbase[ed25519]'

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 or httpx.Timeout (default: 30); None = no timeout
    max_retries=3,               # Default: 3
    debug=False,                 # Log requests
)

Custom httpx client

Pass your own httpx.Client (or httpx.AsyncClient for AsyncHookbase) for proxies, custom transports or TLS settings. The SDK uses it as given and never modifies it: every request is sent to an absolute URL built from base_url, with the SDK's Authorization (an auth= set on your client is not applied to Hookbase requests) and User-Agent headers. If you pass timeout (a number, an httpx.Timeout, or None for no timeout), it is applied to each request; if you leave it out, the client's own timeout applies. close() (and the context manager) leaves a client you supplied open, so close it yourself.

import httpx
from hookbase import Hookbase

http = httpx.Client(verify="/etc/ssl/corp-ca.pem", timeout=10.0)
client = Hookbase(api_key="whr_...", http_client=http)  # uses the 10s client timeout
...
client.close()
http.close()

Inbound Webhooks

# Sources
client.sources.list(page_size=50)  # the API has no search/provider filter on this list
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

# Record the catalog entry a source is made from (create only). Entries with no verifier of
# their own, such as Salesforce, save as Custom HMAC:
client.sources.create({"name": "Salesforce", "slug": "salesforce", "provider": "custom",
                       "catalogProvider": "salesforce"})

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

# HTTP destinations sign every delivery (Standard Webhooks headers), so the receiver can check
# it with Webhook(secret).verify(). Create returns the secret once: put it in your secret store.
# repr() and str() leave it out, so logging the destination doesn't leak it.
signing_secret = dest.signing_secret            # whsec_...; dest.has_signing_secret is True
client.destinations.reveal_secret("dst_id").signing_secret
rotated = client.destinations.rotate_secret("dst_id", grace_period_seconds=3600)
rotated.previous_secret_expires_at              # until then the old secret signs too

# Bridge destinations publish each delivery they receive as an outbound event
from hookbase.models import BridgeConfig, CreateDestinationParams

bridge = client.destinations.create(CreateDestinationParams(
    name="Orders to customers",
    type="bridge",
    config=BridgeConfig(event_type_source="field", event_type_field="type",
                        event_type_prefix="order."),
))
# A bridge's test is a dry run: nothing is published
result = client.destinations.test(bridge.id, payload={"type": "created"})
result.event_type, result.event_type_exists, result.matching_endpoints

# 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")

# While a route's circuit is open its deliveries are held (status "held", hold_expires_at set)
# and go out when it closes. hold_on_circuit_open=False dead-letters them as soon as the circuit
# opens instead.
client.routes.update("route_id", {"holdOnCircuitOpen": False})
client.routes.get("route_id").held_count  # get only; held_count_capped past 10,000

# 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.events.debug("evt_id").curl_command  # plus typed deliveries, pattern hints, circuit state
client.deliveries.replay("del_id")
client.deliveries.bulk_replay(["del_1", "del_2"])

# Replay with edits. payload_patch is an RFC 7386 merge patch on the stored payload (None
# removes a key), so it works on sources that mask fields; modified_payload replaces it. An
# argument left as None is not sent.
client.deliveries.replay(
    "del_id",
    payload_patch={"amount": 10, "coupon": None},
    destination_override="backup-destination",   # id or slug
    headers_override={"X-Replay": "1"},
)

# Transforms & Filters
client.transforms.engines()  # languages this deployment runs, and which are available
client.transforms.create({"name": "Extract", "transformType": "jsonata", "code": "$.data"})
client.transforms.test(code="$.data", payload={"data": {"key": "value"}})  # .result
client.filters.test(
    [{"field": "type", "operator": "equals", "value": "order"}],  # dot paths: "data.status"
    payload={"type": "order"},
    logic="AND",  # or "OR"; sent uppercase
)

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

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"]})

# While an endpoint's circuit is open its messages are held (status "held") and go out when it
# recovers; hold_on_circuit_open=False dead-letters them instead. FIFO endpoints never hold.
client.outbound.endpoints.update("ep_id", {"holdOnCircuitOpen": False})
client.outbound.endpoints.get("ep_id").held_count

# 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
sent = client.outbound.messages.send("app_id", event_type="order.created",
                                     payload={"orderId": "ord_1"})
sent.messages_held  # of messages_queued, those held behind an open circuit (None if none)

# Message Log
client.outbound.message_log.list(application_id="app_id", status="held")  # .hold_expires_at
client.outbound.message_log.get("msg_id").bridge  # set when a bridge destination published it
client.outbound.message_log.list_attempts("msg_id")
client.outbound.message_log.stats()  # .held among the counts

# 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 and creating API keys need a user session: with a whr_ API key the
# API answers 403 (ForbiddenError).
client.organizations.list()
client.organizations.list_members("org_id")
client.organizations.invite("org_id", "user@example.com", "member")
client.api_keys.create({"name": "CI Key", "scopes": ["read", "write"]})

# Analytics: range 1h, 24h, 7d or 30d (or "custom" with start_date/end_date)
stats = client.analytics.dashboard(range="30d", tz="America/New_York")
stats.overview.total_events, stats.latency.percentiles.p95, stats.errors.by_status_code

# Schemas
client.schemas.validate("sch_id", {"orderId": "ord_1"})  # .valid, .errors[].path/.message

# Cron jobs
client.cron_jobs.list()
client.cron_jobs.trigger("cron_id")  # .status, .response_status, .error
client.cron_jobs.list_executions("cron_id", limit=10)

# Tunnels: the auth token is returned once, on create
tunnel = client.tunnels.create({"name": "dev"})
tunnel.auth_token, tunnel.tunnel_url, tunnel.ws_url
client.tunnels.regenerate_token(tunnel.id)  # new token; old connections are dropped
client.tunnels.delete(tunnel.id)

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

# Schemas and cron jobs are not paginated by the API: one page holding everything
schemas = client.schemas.list()

# Cursor-based (inbound events, applications, endpoints, subscriptions, etc.)
apps = client.outbound.applications.list(limit=50)
for app in apps.auto_paging_iter():
    print(app.name)
for event in client.events.list(limit=100).auto_paging_iter():
    print(event.id)

# Limit/offset with no total (deliveries): pages until one comes back short
for delivery in client.deliveries.list(status="failed", limit=100).auto_paging_iter():
    print(delivery.id, delivery.response_status)

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}')

Ed25519 (v1a) endpoints

Endpoints created with signature_scheme="ed25519" are signed with Ed25519 (Standard Webhooks v1a,<sig>). Hookbase keeps the private key; verify with the endpoint's whpk_ public key. This needs pip install 'hookbase[ed25519]'.

from hookbase.models import CreateEndpointParams

ep = client.outbound.endpoints.create(
    "app_id", CreateEndpointParams(url="https://example.com/hook", signature_scheme="ed25519")
)
assert ep.public_key is not None  # set for Ed25519 endpoints
wh = Webhook(ep.public_key)  # "whpk_..."; same verify() API, tolerance and errors as v1
payload = wh.verify(request_body, request_headers)

# Rotation returns the new public key (no secret). During the grace period
# deliveries carry `v1a,<old> v1a,<new>`, so either key verifies them.
rotated = client.outbound.endpoints.rotate_secret(ep.id, grace_period=3600)
rotated.public_key, rotated.previous_public_key

The key decides the scheme (wh.signature_scheme): a whsec_ secret checks v1 entries only and a whpk_ key checks v1a entries only, so a header that mixes both verifies with either.

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})")

Every APIError carries:

  • status_code: the HTTP status actually returned (a ValidationError is 400 or 422).
  • code: the code from the response body, e.g. LIMIT_EXCEEDED or FEATURE_DISABLED on a ForbiddenError. When the body has no code, it is the class default (forbidden, not_found, validation_error, ...).
  • details: the body's details object (for validation failures, {"fieldErrors": ..., "formErrors": ...}), or any extra fields the error sent (such as current and max on LIMIT_EXCEEDED); None when there are none. ValidationError.validation_errors is the fieldErrors map.
  • request_id: the x-request-id response header.

TimeoutError and NetworkError (connection failures, and a base_url that is not an absolute http(s) URL) are raised for requests that got no response.

Retries

Up to max_retries retries (default 3):

  • 429 is retried for every method after Retry-After (seconds or an HTTP date; 60 s when the header is missing or unusable), as long as that wait is at most 60 s. A longer Retry-After is not waited for: the RateLimitError is raised at once with retry_after set, so you decide how to spend that time.
  • Any 5xx, read timeouts and dropped connections are retried with exponential backoff (1, 2, 4 ... s, capped at 10 s, plus up to 1 s jitter) for every method except POST. A POST is retried only when it carries an idempotency key (outbound.messages.send always does).
  • A connection that was never made is always retried.
  • Other 4xx responses are never retried.

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.

Upgrading to 4.2

  • Fix: destinations.list() and get() raised a ValidationError when the organization had a destination of a type other than http, s3, r2, gcs or azure_blob (sqs, eventbridge, servicebus, pubsub, oci_queue, bridge). DestinationType, TransformType and ContentFormat now accept any string, as MessageStatus does, so types added later parse too. "form", which the API never accepted, is gone from ContentFormat.

  • Fix: events.debug() returned an empty curl_command, event.headers and event.payload; they are filled in now. Its deliveries are typed (EventDebugDelivery).

  • destinations.create() returns a DestinationWithSecret, whose signing_secret is the only time the secret is returned; afterwards use reveal_secret(). rotate_secret() takes grace_period_seconds. Destination.has_signing_secret says whether deliveries are signed.

  • Bridge destinations: BridgeConfig for config, Destination.bridge_config to read it, destinations.test(id, payload=...) for a dry run, and the dry-run fields on TestResult.

  • deliveries.replay() takes modified_payload, payload_patch, destination_override, transform_override, headers_override and persist_transform; ReplayResult reports what changed. Passing both payload edits raises ValueError. An argument left as None is not sent, so modified_payload can be any JSON value but null. The same goes for payload on destinations.test().

  • Holds: the held status on deliveries and outbound messages, with hold_expires_at; hold_on_circuit_open, held_count and held_count_capped on routes and webhook endpoints; messages_held on SendEventResponse and held on StatsSummary. MessageStatus also gains awaiting_pull and fifo_waiting.

  • transforms.engines() lists the transform languages the deployment runs.

  • catalog_provider on sources (set on create only).

  • sources.export() returns a raw dict, and the API now sends its ipAllowlist, ipDenylist, encryptFields and maskFields as JSON arrays; they used to be JSON-encoded strings. Code that calls json.loads on them must stop. The Source model already read either form.

  • Secrets and credentials no longer appear in repr() or str():

    • The secrets the API returns, on DestinationWithSecret, DestinationSecret, SourceWithSecret, PendingVerification, WebhookEndpoint, EndpointWithSecret, RotateSecretResult, ApiKeyWithSecret, Tunnel, TunnelToken and PortalToken.
    • The headers and auth configs the API returns in full to a key with the write scope: Destination.headers and auth_config, WebhookEndpoint.headers (and each CustomHeader.value), and CronJob.headers.
    • The credentials you pass in: signing_secret and verify_token on CreateSourceParams and UpdateSourceParams; headers, auth_config and config on CreateDestinationParams and UpdateDestinationParams; headers on the endpoint and cron job params; and the keys on S3Config, GCSConfig and AzureBlobConfig.

    A pydantic.ValidationError from one of these models, or from a list of them, leaves out the input it was given. The values are still sent and still readable from their attributes (dest.signing_secret).

  • Typing: CreateDestinationParams.config and UpdateDestinationParams.config are now dict[str, Any] | BridgeConfig | None, so params.config["bucket"] no longer type-checks until you narrow it with isinstance(params.config, dict). Because DestinationType, TransformType and ContentFormat now include str, mypy reads Destination.type, Transform.transform_type, input_format and output_format as plain str. An exhaustive match or assert_never over their literals no longer type-checks.

Upgrading to 4.1

  • APIError.code now carries the API's code from the response body (for example FEATURE_DISABLED or LIMIT_EXCEEDED on a ForbiddenError, DUPLICATE_NAME on a ConflictError) instead of a fixed string such as "forbidden" or "conflict". The fixed string is still used when the body has no code. Check code that compares .code to those strings; isinstance checks on the error classes are unaffected.
  • ValidationError.status_code is the status actually returned (400 or 422); it used to be always 400.
  • APIError.details is now populated (see Error Handling).
  • A custom http_client no longer needs base_url, auth headers or a timeout configured on it, and close() no longer closes it.
  • timeout=None now means no timeout; leave timeout out to get the default.
  • Every 5xx (not only 500/502/503/504) is retried for retry-safe requests, and Retry-After may be an HTTP date. A 429 whose Retry-After is longer than 60 s is no longer slept through: RateLimitError is raised at once, retry_after set. An empty 2xx body returns None; a 2xx body that is not valid JSON raises APIError (code="invalid_response").
  • Webhook("whsec_...") raises ValueError for a secret that is not valid base64, at construction rather than on the first verify().
  • analytics.dashboard() returns the API's real shape (overview, latency, errors, ...). The old top-level fields (events_received, delivery_success_rate, ...) are now read-only properties derived from overview; before, they were always 0.
  • sources.list(search=, provider=, is_active=), destinations.list(search=, is_active=) and routes.list(source_id=, destination_id=, is_active=) warn (DeprecationWarning) and do not send those filters, which the API never applied.
  • transforms.update() and organizations.update() make a second request to return the stored object (they used to raise on the API's {"success": true} reply).
  • SchemaValidationResult.errors is a list of SchemaValidationError (path, message).

Development

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

License

MIT

Metadata

Release files for hookbase 4.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 4.2.0
File Size Uploaded Provenance Actions
hookbase-4.2.0.tar.gz 142.7 kB With provenance Details for hookbase-4.2.0.tar.gz

Built distribution (wheel)

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

Total release size: 245.2 kB

Release files / hookbase-4.2.0.tar.gz

Download URL hookbase-4.2.0.tar.gz
Size 142.7 kB
Tags Source
SHA-256 checksum
How to use checksums
4ae6f1128898a12a8bca46b2a7f4b07277314f2acec226cbadf52b2d656c9c71
BLAKE2b-256 checksum
How to use checksums
831c32b9b46c29df53c29bb66c5abbf33e609f7737b33b3bf31ef64c1a68fe60
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 13, 2026.

Transparency log

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

Download URL hookbase-4.2.0-py3-none-any.whl
Size 102.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
17d56e74471f875dbcb8df7379c5ef1267adb6f1f1dc6ae447dac1074ae02f24
BLAKE2b-256 checksum
How to use checksums
fc2d32a635d785c325c8c1e6005333b24d231052ba6fc7fc5ba64a55dd3383c2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 13, 2026.

Transparency log

Security for hookbase 4.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-4.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 Nov 13, 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