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 (aValidationErroris 400 or 422).code: thecodefrom the response body, e.g.LIMIT_EXCEEDEDorFEATURE_DISABLEDon aForbiddenError. When the body has nocode, it is the class default (forbidden,not_found,validation_error, ...).details: the body'sdetailsobject (for validation failures,{"fieldErrors": ..., "formErrors": ...}), or any extra fields the error sent (such ascurrentandmaxonLIMIT_EXCEEDED);Nonewhen there are none.ValidationError.validation_errorsis thefieldErrorsmap.request_id: thex-request-idresponse 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 longerRetry-Afteris not waited for: theRateLimitErroris raised at once withretry_afterset, 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.sendalways 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()andget()raised aValidationErrorwhen the organization had a destination of a type other thanhttp,s3,r2,gcsorazure_blob(sqs,eventbridge,servicebus,pubsub,oci_queue,bridge).DestinationType,TransformTypeandContentFormatnow accept any string, asMessageStatusdoes, so types added later parse too."form", which the API never accepted, is gone fromContentFormat. -
Fix:
events.debug()returned an emptycurl_command,event.headersandevent.payload; they are filled in now. Itsdeliveriesare typed (EventDebugDelivery). -
destinations.create()returns aDestinationWithSecret, whosesigning_secretis the only time the secret is returned; afterwards usereveal_secret().rotate_secret()takesgrace_period_seconds.Destination.has_signing_secretsays whether deliveries are signed. -
Bridge destinations:
BridgeConfigforconfig,Destination.bridge_configto read it,destinations.test(id, payload=...)for a dry run, and the dry-run fields onTestResult. -
deliveries.replay()takesmodified_payload,payload_patch,destination_override,transform_override,headers_overrideandpersist_transform;ReplayResultreports what changed. Passing both payload edits raisesValueError. An argument left as None is not sent, somodified_payloadcan be any JSON value but null. The same goes forpayloadondestinations.test(). -
Holds: the
heldstatus on deliveries and outbound messages, withhold_expires_at;hold_on_circuit_open,held_countandheld_count_cappedon routes and webhook endpoints;messages_heldonSendEventResponseandheldonStatsSummary.MessageStatusalso gainsawaiting_pullandfifo_waiting. -
transforms.engines()lists the transform languages the deployment runs. -
catalog_provideron sources (set on create only). -
sources.export()returns a raw dict, and the API now sends itsipAllowlist,ipDenylist,encryptFieldsandmaskFieldsas JSON arrays; they used to be JSON-encoded strings. Code that callsjson.loadson them must stop. TheSourcemodel already read either form. -
Secrets and credentials no longer appear in
repr()orstr():- The secrets the API returns, on
DestinationWithSecret,DestinationSecret,SourceWithSecret,PendingVerification,WebhookEndpoint,EndpointWithSecret,RotateSecretResult,ApiKeyWithSecret,Tunnel,TunnelTokenandPortalToken. - The headers and auth configs the API returns in full to a key with the
writescope:Destination.headersandauth_config,WebhookEndpoint.headers(and eachCustomHeader.value), andCronJob.headers. - The credentials you pass in:
signing_secretandverify_tokenonCreateSourceParamsandUpdateSourceParams;headers,auth_configandconfigonCreateDestinationParamsandUpdateDestinationParams;headerson the endpoint and cron job params; and the keys onS3Config,GCSConfigandAzureBlobConfig.
A
pydantic.ValidationErrorfrom 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). - The secrets the API returns, on
-
Typing:
CreateDestinationParams.configandUpdateDestinationParams.configare nowdict[str, Any] | BridgeConfig | None, soparams.config["bucket"]no longer type-checks until you narrow it withisinstance(params.config, dict). BecauseDestinationType,TransformTypeandContentFormatnow includestr, mypy readsDestination.type,Transform.transform_type,input_formatandoutput_formatas plainstr. An exhaustivematchorassert_neverover their literals no longer type-checks.
Upgrading to 4.1
APIError.codenow carries the API'scodefrom the response body (for exampleFEATURE_DISABLEDorLIMIT_EXCEEDEDon aForbiddenError,DUPLICATE_NAMEon aConflictError) instead of a fixed string such as"forbidden"or"conflict". The fixed string is still used when the body has nocode. Check code that compares.codeto those strings;isinstancechecks on the error classes are unaffected.ValidationError.status_codeis the status actually returned (400 or 422); it used to be always 400.APIError.detailsis now populated (see Error Handling).- A custom
http_clientno longer needsbase_url, auth headers or a timeout configured on it, andclose()no longer closes it. timeout=Nonenow means no timeout; leavetimeoutout to get the default.- Every 5xx (not only 500/502/503/504) is retried for retry-safe requests, and
Retry-Aftermay be an HTTP date. A 429 whoseRetry-Afteris longer than 60 s is no longer slept through:RateLimitErroris raised at once,retry_afterset. An empty 2xx body returnsNone; a 2xx body that is not valid JSON raisesAPIError(code="invalid_response"). Webhook("whsec_...")raisesValueErrorfor a secret that is not valid base64, at construction rather than on the firstverify().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 fromoverview; before, they were always 0.sources.list(search=, provider=, is_active=),destinations.list(search=, is_active=)androutes.list(source_id=, destination_id=, is_active=)warn (DeprecationWarning) and do not send those filters, which the API never applied.transforms.update()andorganizations.update()make a second request to return the stored object (they used to raise on the API's{"success": true}reply).SchemaValidationResult.errorsis a list ofSchemaValidationError(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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.