Webhook Integration

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_api/_models/webhook.py
• src/flext_api/history.json
• src/README.md
• pyproject.toml
• examples/01_basic_usage.py

The Webhook Integration system in FLEXT API provides a robust framework for handling asynchronous event notifications through a structured delivery and retry mechanism. It is designed to manage event envelopes, signature verification, and handler execution with high reliability, leveraging Pydantic 2 for strict data validation.

The system facilitates the registration of event handlers and manages the lifecycle of a webhook event from initial queuing to terminal delivery status (delivered, delivered after retry, or failed). It integrates closely with the project's core constants and type system to ensure type-safety across the delivery pipeline.

Sources: src/flext_api/_models/webhook.py:1-20, src/flext_api/history.json:ChangeSet_constants.py, pyproject.toml:23-40

Core Architecture and Data Models

The webhook system is organized into a centralized model shard within the m.Api namespace. It consists of four primary components: Settings, Event Envelopes, Delivery Records, and Runtime State.

Webhook Models Hierarchy

The following diagram illustrates the relationship between the various webhook models and their role in the system state.

Configuration and Settings

The Webhook.Settings model defines the runtime parameters for webhook operations, including security and retry policies.

Field	Type	Default	Description
secret	str | None	None	Shared secret used for HMAC signature verification.
signature_header	str	X-Webhook-Signature	The HTTP header containing the signature.
algorithm	WebhookAlgorithm	sha256	Supported HMAC algorithm (sha256 or sha512).
max_retries	int	3	Maximum retry attempts per event.
retry_delay	float	1.0	Initial delay before the first retry.
retry_backoff	float	2.0	Multiplier for exponential backoff.

Sources: src/flext_api/_models/webhook.py:22-55, src/flext_api/history.json:ChangeSet_constants.py

Event Lifecycle and Delivery Flow

The delivery process utilizes a dual-queue system (main and retry) to manage high-throughput event processing.

Event Processing Logic

1. Ingestion: Events are wrapped in an Event envelope containing a unique ID, canonical type, and normalized payload.
2. Dispatching: The State model maintains a mapping of handlers indexed by event type.
3. State Management: The State class provides computed properties to track system health, such as event_queue_size, successful_deliveries, and failed_deliveries.

Sources: src/flext_api/_models/webhook.py:57-124, src/flext_api/history.json:ChangeSet_typings.py

Security and Verification

FLEXT API implements HMAC-based signature verification to ensure the integrity and authenticity of incoming webhooks.

Enumerated Constants

The system relies on strict StrEnum definitions for cryptographic algorithms and delivery outcomes.

• WebhookAlgorithm: Supports sha256 and sha512.
• WebhookDeliveryStatus: Tracks outcomes as delivered, delivered_after_retry, or failed.

Sources: src/flext_api/history.json:ChangeSet_constants.py, src/flext_api/_models/webhook.py:38-42

Verification Sequence

Incoming requests are checked against the configured signature_header. The signature is computed using the secret and the raw request body, then compared to the header value.

Implementation Details

The implementation uses MutableMapping and MutableSequence for the runtime state to allow for thread-safe or async-compatible queue operations.

class State(m.FlexibleInternalModel):
    handlers: MutableMapping[str, MutableSequence[t.Api.WebhookHandler]] = u.Field(
        default_factory=dict,
        description="Registered webhook handlers by event type",
    )
    event_queue: MutableSequence[FlextApiModelsWebhook.Webhook.Event] = u.Field(
        default_factory=list, description="Main event queue"
    )

Sources: src/flext_api/_models/webhook.py:91-100

Conclusion

The Webhook Integration module provides a production-grade infrastructure for event-driven architectures. By combining Pydantic-validated models with structured retry logic and HMAC security, it ensures that external system notifications are processed reliably and securely within the FLEXT API ecosystem.