How to Test and Replay Notion Webhooks Locally with Hookdeck

Notion is the go-to workspace for teams managing product roadmaps, wikis, project databases, and knowledge bases. Its integration webhooks deliver real-time event notifications — page creation, database changes, comment activity — to your application via HTTP callbacks. For a comprehensive overview, see our guide to Notion webhooks features and best practices.

Testing Notion webhooks during development requires exposing a local endpoint to the internet, since Notion needs to send HTTP POST requests to a publicly accessible HTTPS URL. Notion also locks the webhook URL after verification, making URL changes impossible without recreating the subscription.

Hookdeck provides an event gateway that can be used to manage inbound webhooks, including monitoring and replaying webhook events. The Hookdeck CLI creates a tunnel from your localhost to a stable public URL, making it easy to receive, inspect, and replay Notion events during development — and the permanent Hookdeck URL means you won't need to recreate your subscription when your local setup changes.

Relaying your Notion webhooks through Hookdeck gives you full visibility into every event delivery, with the ability to inspect payloads, retry failed deliveries, and replay events without re-triggering them in Notion.

This guide walks you through connecting Notion webhooks through Hookdeck to an application running on localhost:

1. Set up a local webhook endpoint
2. Create a Hookdeck connection
3. Create a Notion webhook subscription
4. Test and replay webhook events using the Hookdeck Console

Set up a local webhook endpoint

For this example, we will use the sample Node.js code from Hookdeck's repository. Feel free to follow along with any application or code you might have.

1. Open up your terminal and clone the repository by running:

git clone https://github.com/hookdeck/nodejs-webhook-server-example.git

2. Navigate into the cloned directory and install the dependencies:

cd nodejs-webhook-server-example
npm install

3. Start the server by executing:

npm run dev

The Node.js server starts on http://localhost:1337. See the list of endpoints in the src/routes.ts file.

We will make use of the /notion-webhooks-endpoint.

Create a Hookdeck connection

There are several ways of creating a Hookdeck connection. For this guide, we're using the Hookdeck CLI without a Hookdeck account, so the CLI will dynamically create a connection.

Create Hookdeck connection with Hookdeck CLI

• Install the Hookdeck CLI:

  npm install hookdeck-cli -g
  
  

  yarn global add hookdeck-cli
  
  

    brew install hookdeck/hookdeck/hookdeck
    
    

• Open up your terminal and expose the localhost port with:

hookdeck listen 1337

• The Hookdeck CLI initiates the creation of a guest account that will be used.
• You get prompted to do some basic setup:
  • Create a new source label (ex. notion)
  • Set the path to be forwarded as /notion-webhooks-endpoint
  • Name the connection label (ex. my-application)
• The connection is created, and you are given:
  1. A unique URL for the Hookdeck Console
  2. The webhook URL needed

The same connection can be seen on your Hookdeck guest console after following the link. Copy the Notion Source webhook URL for the next step.

You can create a Hookdeck account to make the URL permanent and enjoy other features. A permanent URL is especially useful with Notion because webhook URLs cannot be changed after verification.

Create a Notion webhook subscription

To set up Notion to deliver events to your Hookdeck URL:

1. Go to notion.so/profile/integrations and select your integration (or create a new one).
2. Navigate to the Webhooks section.
3. Enter the Hookdeck Source URL copied from the previous step as the Webhook URL.
4. Click Create.

Complete the verification handshake

Notion verifies your endpoint before delivering events:

1. Notion sends a POST request to your endpoint containing a verification_token.
2. Your local application receives this token via the Hookdeck tunnel — check your terminal output or the Hookdeck Console to see the payload.
3. Copy the verification_token value.
4. Go back to the webhook settings in Notion and click Verify.
5. Paste the verification_token to complete verification.

The subscription is now active and will start delivering events.

Notion locks the webhook URL after verification. If you need to change it, you must delete the subscription and create a new one. This is another reason to use Hookdeck — the Hookdeck Source URL is permanent, and you can change where it forwards events at any time without touching the Notion configuration.

Grant access to pages and databases

Notion webhooks only fire for content that the integration has access to. To receive events:

1. Open the Notion page or database you want to monitor
2. Click the ... menu in the top right
3. Select Connections > Connect to and choose your integration
4. The integration will now receive events for changes to that page and its children

Testing Notion webhook events

After setting up your local server, configuring the Hookdeck connection, and creating the Notion subscription, it's time to test the integration.

Trigger an event by making a change in Notion that your integration has access to. For example:

• Create a new page in a connected database
• Edit a page that the integration can access
• Add a comment to a connected page

Notion delivers most events within 1 minute, with all events arriving within 5 minutes. High-frequency changes may be aggregated within short time windows.

Upon a successful webhook event trigger, the payload gets relayed by Hookdeck directly to your localhost application.

• On the Hookdeck Console, you should see the request received with a 200 status code.
• Back in your terminal, the event payload is printed by your local server.

Notion uses sparse (thin) payloads — events contain only IDs and metadata, not the full page or database content. To see what changed, your application needs to follow up with a call to the Notion API using the IDs from the event payload.

Retrying error or failed events

In case there are any failed events that don't make it to your destination, Hookdeck provides you with the ability to retry and attempt to deliver any failed or error event.

To retry a failed event:

• Click on the Retry icon by the right of the failed event in the Hookdeck Console

This is especially useful with Notion webhooks because Notion does not provide a manual retry mechanism or browsable delivery logs. Hookdeck fills this observability gap.

For more details on managing Hookdeck events, refer to the Hookdeck documentation.

Conclusion

In this tutorial, you learned how to receive Notion webhook events to an application running on localhost using the Hookdeck CLI and Hookdeck Console.

If you found this helpful, try out the Hookdeck platform that helps you safely consume, monitor, and troubleshoot your Notion webhooks in development and production. Hookdeck provides the observability and retry capabilities that Notion's webhook system lacks, while giving you a permanent URL that works around Notion's URL lock-in after verification.