WebhookEndpoints.md

Webhook endpoints

Endpoints tell Vatly where to send events. Configure these from trusted server-side administration, not from a buyer's request. Examples accept the client from setup; running them changes your Vatly configuration.

Register an HTTPS receiver

import secrets
from vatly import VatlyClient


def example(client: VatlyClient):
    secret = secrets.token_urlsafe(32)
    endpoint = client.webhook_endpoints.create(
        {
            "url": "https://app.example.com/billing/webhook/",
            "secret": secret,
            "enabledEvents": ["order.paid", "subscription.started"],
        }
    )
    # Store secret in your secret manager; do not log it.
    return endpoint.id

Input (wire key)	Required?	Purpose
url	Yes on create	Public HTTPS receiver
secret	Yes on create	Secret used to verify deliveries
enabledEvents	No	Event names to subscribe to; see API reference for defaults

Subscribe to every lifecycle event your integration needs, including cancellation, resume and refund events. The minimal example above is not a complete billing policy.

List, update and remove an endpoint

from vatly import VatlyClient


def example(client: VatlyClient):
    endpoints = list(client.webhook_endpoints.list_all({"limit": 25}))
    endpoint = client.webhook_endpoints.get("webhook_endpoint_example")
    updated = client.webhook_endpoints.update(
        endpoint.id,
        {
            "url": "https://app.example.com/billing/webhook/",
        },
    )
    client.webhook_endpoints.delete(updated.id)
    return endpoints

Deletion returns None. Coordinate secret rotation with your receiver, which can accept old and new secrets temporarily. Do not expose endpoint secrets to browsers.

Response field	Meaning
id, url	Endpoint identity and destination
enabled_events	Event subscriptions
testmode, links	Mode and resource links

Endpoint API reference · Verify deliveries