Introduction

What is hooksentinel?

@hooksentinel/core is a TypeScript-first library for receiving inbound webhooks in Node.js. It sits at the top of your webhook route and handles the part every provider makes you re-implement by hand:

• Verifying the request actually came from the provider (HMAC / signature checks)
• Rejecting replayed or expired requests (timestamp tolerance)
• Deduplicating events so retried deliveries don't run your handler twice
• Acknowledging fast, so the provider doesn't time out and retry unnecessarily
• Giving you a typed event object instead of unknown JSON

It is not a webhook sending platform. It doesn't manage outbound delivery, retries to your customers, or a dashboard of your own webhooks. It's the receiving half — the code that runs inside your server when Stripe, GitHub, or Shopify calls you.

Why it exists

Every project that accepts webhooks ends up writing roughly the same 150–250 lines of plumbing:

1. Get the raw request body before any JSON parsing middleware touches it.
2. Read the provider's signature header and compute an HMAC to compare against it.
3. Check the request timestamp so a captured payload can't be replayed a week later.
4. Parse the body into JSON, ideally with a runtime check that it matches your event shape.
5. Look up whether you've already processed this event ID, because providers deliver at least once, not exactly once.
6. Respond 200 immediately, and only then do the actual work — otherwise the provider retries because your database write took too long.

Get any one of these wrong and you get a real incident: a spoofed webhook mutating billing state, a duplicate charge.succeeded double-fulfilling an order, or a slow handler causing Stripe to retry the same event six times in a row.

hooksentinel is that plumbing, written once, typed, tested against each provider's real signature scheme, and shipped as a single dependency-free package.

Design goals

• TypeScript-first. Event payloads are typed per provider. No any, no manual casting.
• Framework-agnostic core. The verification and idempotency pipeline has no framework dependency. Thin adapters map it onto Express, Fastify, NestJS, Next.js, Hono, and Lambda.
• Zero runtime dependencies. The core package ships with nothing else in node_modules. See Bundle size.
• Fail closed. If a signature can't be verified, the request is rejected. There is no "verify in dev, skip in prod" footgun — you opt into that explicitly if you ever want it.
• Pluggable idempotency. In-memory for local dev, Redis or Prisma for production, or bring your own store by implementing a three-method interface.

hooksentinel vs. Svix vs. Tern

Svix and Tern primarily solve the sending side of webhooks — they're platforms (hosted or self-hosted) that manage outbound delivery, retries, and a customer-facing dashboard for your webhooks product. hooksentinel solves the opposite problem: verifying and handling webhooks sent to you by third parties like Stripe or GitHub.

If you're building a product that emits webhooks to customers, you want Svix or Tern. If you're consuming webhooks from Stripe, GitHub, Shopify, or similar, hooksentinel is a purpose-built fit — and the two are often used together in the same codebase, on opposite ends of the pipe.

Next steps

• Getting started — install and wire up a Stripe webhook in under a minute.
• Supported providers — the full list of built-in signature schemes.
• Frameworks — integration guides for every supported framework.