@notionhq/client
Version:
A simple and easy to use client for the Notion API
56 lines • 2.46 kB
TypeScript
/**
* Helpers for receiving and verifying Notion webhook deliveries.
*
* Notion signs each webhook request with HMAC-SHA256 over the raw HTTP
* body using the subscription's verification token as the key, and sends
* the resulting hex digest in the `X-Notion-Signature` header as
* `sha256=<hex>`. To verify a delivery, callers must pass the body
* **exactly as it arrived over the wire** — any JSON re-serialization
* will change the bytes and invalidate the signature.
*
* The helpers prefer the Web Crypto API (`globalThis.crypto.subtle`)
* when present (browsers, edge runtimes, Node.js >= 18.19) and
* transparently fall back to `node:crypto`'s `webcrypto.subtle` on older
* Node.js 18 builds where `globalThis.crypto` is not yet enabled by
* default. They work without configuration in Node.js, Bun, Deno,
* Vercel Edge Functions, Cloudflare Workers, and modern browsers.
*/
export type VerifyWebhookSignatureArgs = {
/**
* The raw HTTP request body — exactly as received, before any parsing.
* Pass a string for text bodies or a Uint8Array/Buffer for binary-safe
* access. Re-serialized JSON will not verify.
*/
body: string | Uint8Array;
/**
* The value of the `X-Notion-Signature` request header. Verification
* fails (returns false) if this is missing or malformed.
*/
signature: string | null | undefined;
/**
* The verification token configured for this webhook subscription
* (returned by Notion when the subscription was created and surfaced
* during the initial handshake).
*/
verificationToken: string;
};
/**
* Verify that a webhook delivery came from Notion and has not been
* tampered with.
*
* Performs a constant-time comparison; returns `true` only if the
* supplied `signature` matches HMAC-SHA256 of `body` keyed by
* `verificationToken`. Returns `false` (rather than throwing) for any
* malformed input so the caller can respond with a single 401/403 path.
*/
export declare function verifyWebhookSignature(args: VerifyWebhookSignatureArgs): Promise<boolean>;
/**
* Compute the value Notion would send in `X-Notion-Signature` for a
* given body and verification token. Useful for unit-testing webhook
* handlers without standing up a real subscription.
*/
export declare function signWebhookPayload(args: {
body: string | Uint8Array;
verificationToken: string;
}): Promise<string>;
//# sourceMappingURL=webhooks.d.ts.map