lexigram-webhook

Webhook management for the Lexigram Framework — subscription CRUD, delivery tracking, HMAC verification, and dead-letter queue

Overview

lexigram-webhook provides outbound webhook management with subscription CRUD, fan-out delivery with exponential backoff retry, HMAC-SHA256 signing, dead-letter queue, and event bus bridge. It supports in-memory and SQL persistence backends, secret rotation with grace periods, and automatic subscription disable after consecutive failures.

Full documentation: docs.lexigram.dev

Install

uv add lexigram-webhook
# Optional extras
uv add "lexigram-webhook[sql]"

Quick Start

from lexigram import Application
from lexigram.di.module import Module, module

# Import the module from the package
from lexigram.webhook import WebhookModule


@module(imports=[WebhookModule.configure()])
class AppModule(Module):
    pass


async with Application.boot(modules=[AppModule]) as app:
    # use app.container to resolve services
    ...

Configuration

Zero-config usage: Call WebhookModule.configure() with no arguments to use defaults.

Option 1 — YAML file

# application.yaml
webhook:
  store_backend: "memory"
  retry_max_attempts: 5
  retry_base_delay: 1.0
  delivery_timeout_seconds: 30.0
  signature_algorithm: "sha256"

Option 2 — Profiles + Environment Variables (recommended)

export LEX_WEBHOOK__ENABLED=true
# Environment variables for each field

Option 3 — Python

from lexigram.webhook.config import WebhookConfig
from lexigram.webhook import WebhookModule

config = WebhookConfig(store_backend="memory", retry_max_attempts=5)
WebhookModule.configure(config)

Config reference

Module Factory Methods

Key Features

• Subscription CRUD — Create, list, update, deactivate webhook subscriptions
• Secret rotation — Automatic secret generation with grace period for rotation
• Fan-out delivery — Concurrently delivers events to all matching active subscriptions
• Exponential backoff retry — Configurable retry attempts with exponential delay
• Dead-letter queue — Failed deliveries after max attempts are preserved for inspection
• Auto-disable — Subscriptions automatically deactivated after consecutive failures
• HMAC-SHA256 signing — sha256=hex_digest format, compatible with Stripe/GitHub
• Timing-attack prevention — Uses compare_digest for constant-time signature verification
• Event bus bridge — Forward domain events as webhook events to external consumers
• Admin panel integration — WebhookAdminContributor for subscriptions, deliveries, DLQ

Testing

async with Application.boot(modules=[WebhookModule.configure()]) as app:
    # your test code
    ...

Key Source Files