Skip to content

feat: add built-in webhook signature verification - #26

Merged
bjarn merged 1 commit into
mainfrom
feat/webhook-verification
Sep 7, 2026
Merged

feat: add built-in webhook signature verification#26
bjarn merged 1 commit into
mainfrom
feat/webhook-verification

Conversation

@bjarn

@bjarn bjarn commented Sep 7, 2026

Copy link
Copy Markdown
Contributor

The Node SDK has no helper to verify incoming webhooks. Add an exported Webhook class with verify() and verifyHeaders() methods, plus WebhookVerificationError.

The helper checks HMAC-SHA256 signatures against the raw string or Buffer with a constant-time comparison. It checks timestamps with a configurable tolerance (300 seconds by default), checks the delivery header when supplied, and returns decoded JSON only after verification. It accepts multiple v1 signatures and rejects duplicate timestamps and ambiguous headers. The README explains use, error handling, and tolerance behavior.

Validation:

  • All 90 tests passed, including 43 webhook tests.
  • Lint, TypeScript checks, and package build passed.
  • Both CommonJS and ESM builds accepted an independent Python HMAC signature with a UTF-8 payload.

A tolerance of zero accepts only the current second. Timestamp checks do not prevent duplicate delivery within the allowed period; the README explains this limit.

@bjarn
bjarn requested a review from Bjornftw September 7, 2026 17:34
@bjarn
bjarn merged commit f256598 into main Sep 7, 2026
7 checks passed
@bjarn
bjarn deleted the feat/webhook-verification branch September 7, 2026 17:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants