Module webhook 

Webhook handling with signature verification.

Forge provides a structured way to receive webhooks from external services with automatic signature verification and idempotency handling.

Signature Verification

Webhooks can verify signatures using HMAC-SHA256 or other algorithms:

#[forge::webhook(
    path = "/webhooks/stripe",
    signature = "hmac_sha256",
    secret_env = "STRIPE_WEBHOOK_SECRET"
)]
async fn handle_stripe(ctx: &WebhookContext, payload: StripeEvent) -> WebhookResult {
    // Signature already verified
}

Idempotency

Webhooks can be configured to deduplicate based on a header or payload field:

#[forge::webhook(
    path = "/webhooks/github",
    idempotency_key = "header:X-GitHub-Delivery"
)]

Key Types

• WebhookContext - Request context with headers and raw body
• SignatureConfig - Signature verification settings
• IdempotencyConfig - Deduplication settings

Structs

IdempotencyConfig

Configuration for webhook idempotency.

SignatureConfig

Configuration for webhook signature validation.

WebhookContext

Context available to webhook handlers.

WebhookInfo

Metadata for a registered webhook handler.

WebhookSignature

Helper for constructing signature configurations.

Enums

IdempotencySource

Source for extracting idempotency key.

SignatureAlgorithm

Supported signature algorithms.

WebhookResult

Constants

DEFAULT_REPLAY_WINDOW_SECS

Default replay window for non-Stripe webhook signature schemes (5 minutes). Stripe enforces its own 5-minute window via the t= field in its header and ignores this value.

REPLAY_TIMESTAMP_HEADER

Header used by non-Stripe schemes to convey the request’s unix-seconds timestamp. Senders that don’t ship this header are rejected when the scheme requires replay protection.

Traits

ForgeWebhook

Trait for inbound webhook handlers.