Python SDK

The Python SDK returns validated pydantic v2 models with typed, snake_cased attributes. Python 3.10+, built on httpx.

pip install webhook-co

Quickstart

import os
from webhook_co import WebhookClient

client = WebhookClient(api_key=os.environ["WEBHOOK_API_KEY"])

endpoint = client.endpoints.create(name="orders-prod")
print(endpoint.ingest_url)  # the endpoint's signed ingest URL

Pagination

List methods return a Paginator you can iterate directly:

for endpoint in client.endpoints.list(name="prod"):
    print(endpoint.id)

# Collect everything (careful with large result sets):
failed = client.deliveries.list(status=["failed"]).collect()

# One page at a time:
page = client.endpoints.list_page(limit=50)
print(page.items, page.next_cursor)

Errors

Every failure is a WebhookError subclass, so you can narrow with except:

from webhook_co import WebhookRateLimitError, WebhookNotFoundError

try:
    client.endpoints.get(endpoint_id)
except WebhookNotFoundError:
    ...  # 404
except WebhookRateLimitError as err:
    print(f"retry after {err.retry_after_s}s")

Each error carries code, status, and request_id when present.

Retries & idempotency

The client retries idempotent requests on transient failures with capped exponential backoff and jitter, honouring Retry-After, and never blind-retries a non-idempotent write. Replays carry an idempotency key (auto-generated if you don’t pass one):

import uuid

client.events.replay(
    event.id,
    target={"kind": "destination", "destinationId": destination_id},
    idempotency_key=str(uuid.uuid4()),
)

Recovering a lost ingest URL

The ingest URL is a bearer credential, but it is not a one-time secret: the token is sealed at rest, so you can read it back any time. You never have to rotate to recover it — and you shouldn’t, because rotating revokes the live URL and breaks every sender still posting to it.

revealed = client.endpoints.reveal_ingest_url(endpoint.id)
print(revealed.ingest_url)

ingest_url is None only for endpoints created before sealed storage; rotate those once to mint a fresh, re-readable one.

Triggers (webhook → agent)

Wait for an endpoint’s events with an ack-by-cursor loop. wait is a short poll — it returns immediately with whatever is past your cursor, so there is no held connection.

trigger = client.triggers.create(endpoint_id=endpoint.id)

cursor = None
while True:
    page = client.triggers.wait(trigger.id, cursor=cursor)
    for event in page.events:
        handle(event)
    cursor = page.next_cursor  # feed straight back in
    if page.caught_up:         # <- the caught-up signal
        time.sleep(1)

next_cursor is None only when you sent no cursor and there were no events — it means “start from the oldest retained event”, not “caught up”. caught_up is the caught-up signal. Delivery is at-least-once: a crash before you persist the cursor re-reads rather than loses, so dedupe on the event id. Pass include_body=False for summary-only pages (it skips the payload fetch).

Usage, deletes, and dedup config

usage = client.usage.get()                       # events counted, the cap, whether you are paused
client.endpoints.update(id, dedup_config=None)   # None resets to the default
client.events.delete(event_id)                   # redacts + purges ONE event; usage is not reduced

Version advisories

If the server sees you are on an old SDK, it rides an advisory back on a response you already made — the SDK never polls PyPI on your behalf, so there is no extra request and nothing to break offline. By default it emits one UserWarning. Route it into your own logs instead:

client = WebhookClient(
    api_key=api_key,
    on_advisory=lambda a: log.warning(a.message),  # fires at most once per client
    # silence_advisories=True,                     # …or hear nothing at all
)

Configuration

client = WebhookClient(api_key, max_retries=4, timeout_s=15)  # defaults: 2 retries, 30s

# As a context manager, to close the connection pool:
with WebhookClient(api_key) as client:
    client.whoami()

Full source, changelog, and issues: github.com/webhook-co/webhook.

CLI

SDKs

Quickstart

Errors

Retries & idempotency

Recovering a lost ingest URL

Triggers (webhook → agent)

Usage, deletes, and dedup config

Version advisories

Configuration

​Quickstart

​Pagination

​Errors

​Retries & idempotency

​Recovering a lost ingest URL

​Triggers (webhook → agent)

​Usage, deletes, and dedup config

​Version advisories

​Configuration

Quickstart

Pagination

Errors

Retries & idempotency

Recovering a lost ingest URL

Triggers (webhook → agent)

Usage, deletes, and dedup config

Version advisories

Configuration