webhook

const webhook: object

Defined in: src/helpers/webhook.helpers.ts:92

Helpers for signing and verifying Notion webhook payloads.

Type Declaration

sign

sign: (body, verificationToken) => string

Sign a payload to generate test webhook signatures.

Parameters

body

unknown

The payload to sign. This function signs a string as-is. It converts anything else with JSON.stringify first. This is safe because the caller controls the serialization of their own payload.

verificationToken

string

The webhook subscription’s verification token

Returns

string

The sha256=<hex digest> signature

Example

const signature = webhook.sign({ event: 'page.updated' }, verificationToken);

verifySignature

verifySignature: (rawBody, signatureHeader, verificationToken) => boolean

Verify an incoming webhook’s X-Notion-Signature header via constant-time comparison.

IMPORTANT: rawBody must be the exact raw request body that Notion sent. Do not use JSON.stringify(parsedBody). Re-serializing a parsed object can produce a different byte sequence (key order, whitespace) than the original signed body, and this silently breaks verification. Use your framework’s raw-body access, for example Express’s express.raw() or req.rawBody. Do not use req.body after JSON middleware parses it.

Parameters

rawBody

string

The exact raw request body string Notion sent

signatureHeader

string | null | undefined

The value of the X-Notion-Signature request header

verificationToken

string

The webhook subscription’s verification token

Returns

boolean

true if the signature is valid. Returns false for a mismatch or malformed input. This function never throws.

Example

const isValid = webhook.verifySignature(rawBody, req.headers['x-notion-signature'], verificationToken);

Example

import { webhook } from '@visus-io/notion-sdk-ts';

const isValid = webhook.verifySignature(rawBody, req.headers['x-notion-signature'], verificationToken);