Research: Port Svix webhook verification and normalization patterns

[haasonsaas]

Context

Svix (3.2k stars, Rust, MIT) is the leading OSS webhook infrastructure platform with verification, retry, and delivery guarantee patterns.

What to yoink

• Webhook signature verification — HMAC-based payload verification per provider (each SaaS has different signing schemes)
• Provider-specific payload normalization — standardize diverse webhook payloads into a common event schema
• Retry with exponential backoff — configurable retry policies with dead-letter handling
• Event type registry — typed event schemas with versioning and backwards compatibility
• Delivery guarantees — at-least-once delivery with idempotency key deduplication

Approach

Ensemble-tap already uses NATS JetStream + ClickHouse for event streaming. The webhook ingestion layer is where Svix patterns apply:

1. Study Svix's webhook verification library for provider-specific HMAC schemes
2. Port payload normalization patterns for SaaS-specific webhook formats
3. Borrow event type registry design for typed, versioned event schemas
4. Evaluate delivery guarantee patterns alongside JetStream's built-in guarantees

References

• https://github.com/svix/svix-webhooks
• Svix also publishes standalone webhook verification libraries in multiple languages

Priority

Tier 2 — Clean patterns for the messy reality of SaaS webhook diversity