django-outbound-webhooks

Outbound webhooks for Django, built on django-domain-events.

Your customers subscribe to domain events, not to your post_save signals. An endpoint is a row a customer owns: a URL, a secret, the events it wants and the body format it was integrated against. Delivery is a durable receiver, so retry, backoff, dead-lettering and replay are inherited rather than rebuilt.

Install

pip install django-outbound-webhooks

Body formats

A customer's endpoint is pinned to one published format version when it registers, and that version is frozen: changing what it renders would change what an already-integrated consumer receives, under a signature that still verifies. A change is a new version.

register_endpoint(
    name="Acme production",
    url="https://acme.example/hooks/orders",
    secret=secret,
    event_names=["shop.OrderPlaced"],
    # Both optional. Without format_name, DEFAULT_FORMAT decides; without
    # format_version, the latest is pinned and that number is written down.
    format_name="cloudevents",
)

cloudevents is published only when the deployment says which system produced the events, because the specification requires a non-empty source and an invented one would be signed into every body:

DJANGO_OUTBOUND_WEBHOOKS = {"CLOUDEVENTS_SOURCE": "https://shop.example/events"}

Your own format is an object with a name, a version and a render(), which you publish from your AppConfig.ready():

from django_outbound_webhooks import formats

formats.register(MyFormat())

It does not have to inherit from anything: BodyFormat is a Protocol. The registry checks at registration that what you handed it can actually render a delivery, because a format is published once at startup and called hours later in another process.

Operations

from django_outbound_webhooks import reactivate_endpoint, replay_delivery, rotate_secret

replay_delivery(message_id="018f...")  # a new delivery of a logged one
rotate_secret(endpoint, new_secret=secret)  # both secrets sign until the window closes
reactivate_endpoint(endpoint)  # back on, and the failure count cleared

A replay is a new delivery: a new webhook-id (a receiver deduplicates on that one), the endpoint's current format and secrets, and its own delivery row, attempt budget and log rows. It refuses rather than firing something that cannot arrive - a deleted endpoint, an inactive one, an event retention has pruned.

A rotation overlaps. The specification carries several signatures in one header and a receiver accepts the delivery if any verifies, so the customer deploys the new secret on their own schedule and nothing is dropped in between.

An endpoint that stops answering is switched off after AUTO_DISABLE_AFTER_DEAD_DELIVERIES consecutive dead deliveries - each of which has already spent a whole attempt budget across processes and hours, so the default of twenty is an endpoint that is gone rather than one having a bad afternoon. A delivery that lands resets the count. Somebody has to tell the customer, so it fires an event you can receive:

from django_domain_events import receiver
from django_outbound_webhooks.operations.endpoint_disabled import EndpointDisabled


@receiver(EndpointDisabled, key="acme.email_the_customer")
def email_the_customer(disabled: EndpointDisabled) -> None: ...

Admin

Add django.contrib.admin and the endpoints and the delivery log are there: per- endpoint health in the unit that means something, a link from each endpoint to its own attempts, replay as an action on the log, and reactivation as an action on the registry.

No signing secret is ever rendered, and endpoints cannot be created there - register_endpoint is where the rules live. tenant and the pinned format are read-only: the first decides whose payload reaches whose URL, and the other two are the shape the customer wrote code against.

Both actions declare their permission, because Django offers an action without one to anyone who can open the changelist. Replay is gated on the endpoint's change permission rather than the log's, so a support user can be given the log to read without being able to make deliveries happen.

Status

Released and in use, pre-1.0. Shipped: the registry, signing, delivery with a lease-bounded retry, the request-forgery policy, the delivery log, two body formats, the operations above and the admin surface. What 1.0 waits on is time in production rather than a feature.