Export verifyWebhookSignature as standalone function from webhooks/verify.ts

[Kingsman-99]

Description

src/webhooks/verify.ts contains signature verification logic but it is not exported as a standalone function from src/index.ts. Consumers building their own webhook receivers cannot import the verifier directly — they must copy the logic. This issue exposes it as a first-class SDK export.

Acceptance Criteria

• verifyWebhookSignature(payload: string, signature: string, secret: string): boolean exported from src/webhooks/verify.ts
• Uses HMAC-SHA256: crypto.createHmac('sha256', secret).update(payload).digest('hex') and compares with signature using a timing-safe comparison (crypto.timingSafeEqual)
• Returns false (never throws) when signature is malformed or lengths differ
• WebhookVerificationError class exported for consumers who prefer throwing — wraps verifyWebhookSignature and throws if it returns false
• Both exported from src/index.ts
• Unit tests: valid signature returns true, wrong secret returns false, tampered payload returns false, mismatched length returns false without throwing

Context

• Target files: src/webhooks/verify.ts, src/index.ts
• Must use crypto.timingSafeEqual to prevent timing attacks — not ===

[waterWang]

/attempt

Would like to take this bounty. I will implement verifyWebhookSignature with HMAC-SHA256 + crypto.timingSafeEqual, add WebhookVerificationError, export both from src/index.ts, and write unit tests covering valid signature / wrong secret / tampered payload / mismatched length. Expect a PR shortly.

[ZacLou]

I'd like to take this on. The implementation is well-defined: export verifyWebhookSignature from src/webhooks/verify.ts using HMAC-SHA256 with crypto.timingSafeEqual for timing-safe comparison, plus a WebhookVerificationError class that wraps it and throws on failure.

I have prior context on this codebase from PR #810 (searchByMemo, currently open). Happy to deliver a clean PR with full unit test coverage once assigned.

[woahwhattheheck]

Submitted a PR for this: #829

It covers the acceptance criteria above, and also fixes a crash I hit while
implementing them. verifyWebhookSignature currently throws TypeError
rather than returning false when the secret or payload is not a string —
the hex guard runs before createHmac()/.update() receive them:

verifyWebhookSignature(body, sig, undefined)   // TypeError: The "key" argument must be of type string...
verifyWebhookSignature(undefined, sig, secret) // TypeError: The "data" argument must be of type string...

That is the common case in a webhook route: an unset WEBHOOK_SECRET, or
req.body read before a body parser runs, becomes a 500 instead of a 401.

One design note worth flagging: src/index.ts already exports a
verifyWebhookSignature — the async, isomorphic one from
./webhookMiddleware.js, which also accepts an object payload. Re-exporting
the synchronous Node-only helper under that same name would replace it and
break object-payload callers and browser/edge consumers. So the PR keeps the
existing export as-is and adds the sync helper as verifyWebhookSignatureSync
alongside WebhookVerificationError and assertWebhookSignature. Glad to
consolidate the two verifiers into one entry point instead if that is the
direction you want — that felt like an API call for a maintainer rather than
something to decide inside a bug fix.