Drop-in Convex component for reliable webhook ingestion with signature verification, deduplication, and automatic retry handling.
npm install convex-webhook-receiverThe Webhook Receiver component handles inbound webhook processing for Convex apps with signature verification, automatic deduplication, and reliable async processing. It supports 8+ providers (GitHub, Stripe, Slack, Twilio, etc.) with built-in retry logic and dead-letter queue management. Webhooks return 200 OK immediately while your handler functions process events in the background with exponential backoff on failures.
The Webhook Receiver component automatically retries failed webhook processing with exponential backoff (default 3 attempts). Failed events that exhaust retries are moved to a dead-letter queue where you can query and manually replay them using the built-in API.
Configure the component with provider: 'github' and your webhook secret to automatically verify HMAC-SHA256 signatures via the X-Hub-Signature-256 header. The component also deduplicates GitHub webhooks using the X-GitHub-Delivery header.
The component automatically deduplicates webhooks using provider-specific delivery ID headers like X-GitHub-Delivery. For providers without built-in dedup headers, specify a custom dedupKeyHeader to use any unique identifier from the webhook headers.
Register your handler as an internal action that receives the raw webhook payload and headers. The HTTP endpoint returns 200 OK immediately while your handler processes the webhook data in the background, preventing timeouts and ensuring reliable delivery confirmation.
The Webhook Receiver component has built-in support for GitHub, Stripe, Slack, Twilio, Shopify, Linear, Discord, and generic HMAC-SHA256 webhooks. You can also pass a custom verifier function to handle any other signature scheme.
The component uses exponential backoff with a default of 3 attempts (1s, 2s, 4s intervals, capped at 30 minutes). You can configure maxAttempts globally or per-handler. Events that exhaust all retries are moved to a dead-letter queue for manual inspection and replay.
Yes, the Webhook Receiver component supports automatic deduplication via provider headers (like X-GitHub-Delivery), custom headers specified with dedupKeyHeader, or you can handle deduplication logic within your handler action for complete control.
The Webhook Receiver component exports test helpers for use with convex-test. Register the component's schema and modules in your test setup, then you can test your webhook handlers with mock payloads and verify the processing behavior.