Reliable Webhooks

A webhook handler looks like twenty lines until it meets production. Then the same Stripe event arrives twice, your database blips during a deploy, a forged request hits the endpoint, or a worker is killed halfway through fulfilling an order. Reliable Webhooks is the part you would otherwise design, write and test yourself: verify, store, acknowledge, process, retry, and dead-letter.

The failure cases it handles

How it looks

const receiver = createWebhookReceiver({
  provider: stripeProvider({ secret: process.env.STRIPE_WEBHOOK_SECRET! }),
  store: new PostgresStore(pool),
  handlers: {
    "checkout.session.completed": async ({ event, idempotencyKey }) => {
      await grantAccess(event.payload, idempotencyKey); // runs once per event
    },
  },
});

// app/api/webhooks/stripe/route.ts
export const POST = (request: Request) => receiver.handle(request);

// cron, every minute
await receiver.processDue();

What's in the package

src/            ~780 lines of strict TypeScript, zero runtime dependencies
migrations/     one idempotent SQL file
tests/          60 tests: providers, receiver, retries, Node adapter, store contract (Memory + Postgres)
examples/       offline demo (npm run demo), Next.js route + cron worker, node:http / Express
docs/           ARCHITECTURE.md (lifecycle and why), SECURITY.md (threat model, deployment checklist)
README.md  CHANGELOG.md  LICENSE.md

The test suite includes concurrency tests against a real PostgreSQL database and a contract suite you can run against your own store implementation. You can run npm run demo the moment you unzip it to watch a forged request, a duplicate, an outage and a recovery play out against a real HTTP server.

Who it is for

Teams on Node and TypeScript who take payments, sync with GitHub or receive webhooks from any HMAC-signing service, and want it to be correct without building a queue system.

Who it is not for

• Sending webhooks to your own customers (this is the receiving side).
• Very high volume pipelines: events are processed through PostgreSQL, which is comfortable for typical SaaS traffic but not a replacement for Kafka-scale ingestion.
• Non-JavaScript runtimes.
• Exactly-once side effects: no webhook system can promise that. The kit gives you at-least-once delivery plus an idempotency key per event so your handler can be made safe.

The security design is documented in the package (docs/SECURITY.md) with a threat model. In short:

• Authenticity: HMAC-SHA256 over the raw body using Web Crypto's constant-time verify; every candidate secret is checked without early exit; malformed headers always end in 401, never an unhandled exception.
• Replay: timestamp tolerance where the provider sends one (Stripe default 300 s); idempotency on the delivery id everywhere.
• Abuse: request body capped (default 1 MiB) both by Content-Length and while streaming.
• Injection: all SQL values are bound parameters; the one interpolated identifier (table name) is validated; a test stores hostile payload text.
• Privacy: logs contain ids, event types and attempt numbers only. No payloads, headers or secrets. This is tested.
• Supply chain: zero runtime dependencies; npm audit --omit=dev is clean.
• Honest limits: no IP allow-listing, no ordering guarantees, no encryption at rest (your database's job), at-least-once delivery. These are documented along with a deployment checklist.

Softreuse Commercial License — Reliable Webhooks

Version 1.0 · Copyright © Softreuse. All rights reserved.

This is the license that comes with your purchase of this package ("the Software"). Please read it; it is short on purpose.

1. What you may do

You (the individual or single company that purchased the Software, "Licensee") may, forever, for the versions covered by Section 4:

• use, copy and modify the source code in any number of projects that you or your company own or build for your own use, commercial or not;
• let your employees and contractors work with the source for those projects;
• ship products that contain or are built from the Software (including compiled or bundled) to your own users and customers;
• keep your modifications private.

2. What you may not do

• Redistribute, resell, sublicense, publish or share the Software's source code, in original or modified form, as a standalone product, template, boilerplate, starter kit, library, SaaS feature-for-feature clone, course material or marketplace listing.
• Publish the Software's source in a public repository or package registry. (Private repositories of your team are fine. Publishing an application that merely uses the Software is fine.)
• Share your download access or purchase with people outside your company.
• Remove copyright or license notices from the files.

If you are a consultancy building a product for a client, the client needs their own license unless the client is the owner of the resulting project and you transfer the project (not the Software as a standalone asset).

3. Ownership

Softreuse keeps ownership of the Software. You own everything you build with it.

4. Updates

Your purchase includes all releases of this product within the major version you bought (for example every 1.x release if you bought 1.0.0), delivered through your Softreuse account. A new major version (2.0.0) is a new paid release; versions you already have keep working under this license forever.

5. Warranty and liability

The Software is provided "as is", without warranty of any kind. Softreuse tests the Software and publishes known limitations, but you are responsible for evaluating it for your use, including security review of your own deployment. To the maximum extent permitted by law, Softreuse's total liability for any claim is limited to the amount you paid for the Software, and Softreuse is not liable for indirect or consequential damages (lost profits, lost data, business interruption).

6. Refunds

If the Software does not work as documented, tell us within 14 days of purchase and we will refund you in full. Refunded licenses end at the moment of refund.

7. Termination

This license ends automatically if you breach Section 2. Sections 3, 5 and 7 survive termination.

8. Contact

support@softreuse.com