Webhook Endpoints

Manage your webhook subscriptions and audit deliveries. The signature verifier for receiving webhooks is documented separately on the Webhooks page.

Namespace: client.webhooks_management.

Methods

`register`

endpoint = client.webhooks_management.register(
    url="https://example.com/webhooks/easy",
    events=["payment.created", "subscription.updated", "invoice.paid"],
    idempotency_key="webhook-prod-2026-05",
)

# `endpoint.secret` is returned once — store it now; you cannot fetch
# it again.
SECRET = endpoint.secret

Returns: RegisteredWebhookEndpoint. Pass events=None (the default) to subscribe to every supported event.

`list`

endpoints = client.webhooks_management.list()

Returns list[WebhookEndpoint]. The signing secret is not included on subsequent reads — only on the original register(...) response.

`update`

endpoint = client.webhooks_management.update(
    "we_123",
    url="https://example.com/webhooks/easy/v2",
    events=["payment.*"],
)

`delete`

client.webhooks_management.delete("we_123")

`list_deliveries`

page = client.webhooks_management.list_deliveries(
    event_type="payment.created",
    success=False,
    created_after="2026-05-01T00:00:00Z",
    created_before="2026-05-02T00:00:00Z",
    limit=100,
    offset=0,
    include_counts=True,
)
print(page.get("total"))
for d in page.get("data", []):
    print(d["id"], d["status_code"])

Returns the raw paginated data payload (dict). Use endpoint_id= to scope to a single endpoint, or call list_endpoint_deliveries for the same effect with the endpoint in the URL.

`list_endpoint_deliveries`

page = client.webhooks_management.list_endpoint_deliveries(
    "we_123",
    success=False,
    limit=50,
)

Object shape

WebhookEndpoint:

Field	Type
`id`	`str`
`url`	`str \| None`
`status`	`str \| None`
`events`	`list[str] \| None`
`created_at`	`str \| None`
`updated_at`	`str \| None`

RegisteredWebhookEndpoint extends the above with secret: str | None — only populated on creation.

WebhookDelivery:

Field	Type
`id`	`str`
`endpoint_id`	`str \| None`
`event_type`	`str \| None`
`success`	`bool \| None`
`attempt` / `attempt_number`	`int \| None`
`status_code`	`int \| None`
`response_body`	`str \| None`
`created_at` / `delivered_at`	`str \| None`

Examples

Bootstrap an endpoint and store the secret

endpoint = client.webhooks_management.register(
    url=f"{PUBLIC_BASE_URL}/webhooks/easy",
    events=["payment.created", "invoice.paid", "subscription.updated"],
    idempotency_key=f"webhook-{ENV}-2026-05",
)

# Persist atomically — losing the secret means re-registering.
secrets_store.put("EASY_WEBHOOK_SECRET", endpoint.secret)

Audit failed deliveries from the last 24 hours

import datetime as dt

since = (dt.datetime.now(dt.timezone.utc) - dt.timedelta(days=1)).isoformat()
page = client.webhooks_management.list_deliveries(
    success=False,
    created_after=since,
    limit=200,
)
for d in page.get("data", []):
    print(d["event_type"], d["status_code"], d["response_body"])

Rotate an endpoint URL

client.webhooks_management.update(
    "we_123",
    url="https://example.com/webhooks/easy/v2",
)

Webhook Endpoints

On this page