Crate fraiseql_webhooks 

fraiseql-webhooks

Inbound webhook receiver for FraiseQL — receives, verifies, and routes HTTP callbacks from third-party services into your database.

Inbound vs. Outbound

FraiseQL has two webhook-related crates with complementary roles:

Crate	Direction	Purpose
fraiseql-webhooks	Inbound	Receive callbacks from Stripe, GitHub, Shopify, …
fraiseql-observers	Outbound	Emit notifications when your data changes

Use fraiseql-webhooks when you want to react to events from external providers. Use fraiseql-observers when you want to push events to subscribers.

Supported Providers

Built-in signature verification for:

• Stripe — HMAC-SHA256 on Stripe-Signature header with replay protection
• GitHub — HMAC-SHA256 on X-Hub-Signature-256 header
• Shopify — HMAC-SHA256 on X-Shopify-Hmac-Sha256 header
• SendGrid — ECDSA on X-Twilio-Email-Event-Webhook-Signature
• Paddle — RSA-SHA256 on Paddle-Signature header
• Custom providers via the traits::SignatureVerifier trait

Security Properties

• Constant-time comparison — prevents timing attacks on HMAC tokens
• Replay protection — Stripe/Paddle timestamps validated within a 5-minute window
• Idempotency — duplicate delivery is detected and silently discarded
• Transaction boundaries — each webhook is processed inside a database transaction

Quick Start

See docs/architecture/webhooks.md for the full integration guide.

See Also

• docs/architecture/webhooks.md — full design doc
• fraiseql-observers — outbound change notifications

Features

• 15+ provider support: Stripe, GitHub, Shopify, and more
• Signature verification: Constant-time comparison for security
• Idempotency: Prevent duplicate event processing
• Event routing: Map webhook events to database functions
• Transaction boundaries: Correct isolation levels for data consistency

Re-exports

pub use config::WebhookConfig;

pub use config::WebhookEventConfig;

pub use signature::SignatureError;

pub use traits::Clock;

pub use traits::EventHandler;

pub use traits::IdempotencyStore;

pub use traits::SecretProvider;

pub use traits::SignatureVerifier;

pub use transaction::WebhookIsolation;

pub use transaction::execute_in_transaction;

Modules

config

Webhook configuration structures.

signature

Webhook signature verification.

testing

Mock implementations for testing.

traits

Testing seams for webhook dependencies.

transaction

Transaction boundary management for webhook processing.

Enums

WebhookError

Errors that can occur during webhook request processing.

Type Aliases

Result

Result type for webhook operations