---
name: bijection-webhook-receiver
description: "Evaluate and integrate the Webhook Receiver component with Bijection."
---

# Webhook Receiver

Inbound webhook handling

- Package: @bijectionhq/webhook-receiver
- Category: Messaging
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/webhook-receiver/tree/41aa9a2fd8ac767f9110816ea5c5147e6ff35318
- Upstream: https://github.com/david-potgieter/convex-webhook-receiver/tree/05da1e8eed507b30160525e8a01eaa54c3c5d3c6
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/webhook-receiver

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/webhook-receiver.git
cd webhook-receiver
git checkout 41aa9a2fd8ac767f9110816ea5c5147e6ff35318
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes convex-webhook-receiver. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


# Webhook Receiver

## Instructions

Use Webhook Receiver to drop-in convex component for reliable webhook ingestion with signature verification, deduplication, and automatic retry handling. This Convex component integrates directly with your backend.

### Installation

```bash
npm install convex-webhook-receiver
```

### Capabilities

- Verify webhook signatures from GitHub, Stripe, Slack, and 8 other providers out of the box
- Eliminate duplicate webhook processing with automatic deduplication using provider delivery IDs
- Handle webhook failures gracefully with configurable retry logic and dead-letter queue management
- Process webhooks asynchronously while returning immediate 200 OK responses to providers

## Examples

### how to handle webhook retries in Convex

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.

### verify GitHub webhook signatures in Convex

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.

### prevent duplicate webhook processing Convex

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.

### async webhook processing Convex actions

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.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Webhook Receiver is not needed

## Troubleshooting

**Which webhook providers does this component support?**

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.

**How does the retry mechanism work?**

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.

**Can I customize the deduplication logic?**

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.

**How do I test webhooks with this component?**

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.

## Resources

- [npm package](https://www.npmjs.com/package/convex-webhook-receiver)
- [GitHub repository](https://github.com/david-potgieter/convex-webhook-receiver)
- [Live demo](https://github.com/david-potgieter/convex-webhook-receiver/tree/main/example)
- [Convex Components Directory](https://www.convex.dev/components/convex-webhook-receiver)
- [Convex documentation](https://docs.convex.dev)