Notion webhooks

Notion webhooks are signed HTTP POST requests that tell your connection when pages, databases, comments and other workspace content change, carrying IDs rather than the content itself.

31 events covered

These pages cover connection webhooks, which a connection subscribes to and Notion signs. The Send webhook action in buttons and database automations is a separate no-code feature: it POSTs the properties you pick to a URL, and Notion documents no signature for it.

How Notion webhooks work

Webhooks push changes to your server, so you don't have to poll the Notion API. A connection subscribes to event types in its Webhooks tab, and Notion sends an HTTPS POST with a JSON body when something the connection can access changes. Each event is a thin signal: it says what changed and gives its ID, and you call the API for the content. Most events should arrive within a minute, and all within 5 minutes.

The body's type names the event, such as page.content_updated, and entity gives the ID and type of what changed. id identifies the event, timestamp says when it happened, and data holds event-specific fields such as updated_blocks. Notion batches rapid changes to one entity into a single aggregated event. Each subscription has an API version, named in the body's api_version: moving to 2025-09-03 replaces database.content_updated and database.schema_updated with data_source.* events.

Key facts

Signature header
X-Notion-Signature

Format: sha256=<hex>

Scheme
HMAC-SHA256

Docs discrepancy

Notion's sample code hashes JSON.stringify(body) over a parsed body, while the same page's SDK note says re-serialized JSON fails verification. The sample only works when serialization reproduces the bytes. Hash the raw body.

Docs ↗
Signed material
{raw body}

The request body exactly as sent, with nothing added. No timestamp is added to the signed content.

How events are identified
type field in the body
Body format
JSON

Content type: application/json.

API versioning
api_version in the body

Seen: 2022-06-28, 2025-09-03, 2026-03-11.

Envelope
id, timestamp, workspace_id, workspace_name, subscription_id, integration_id, type, authors, accessible_by, attempt_number, api_version, entity, data
Agent skill
npx skills add hookdeck/webhook-skills --skill notion-webhooks

Verify Notion webhooks →

Setting up Notion webhooks

  • Create a subscription in the Webhooks tab of your connection settings, with a public HTTPS URL and the event types you want. You can't change the URL after verification, only delete and recreate the subscription.
  • Complete the handshake, because nothing is delivered until you do. Notion POSTs a one-time verification_token to your URL. Copy it, click Verify in the Webhooks tab and paste it there. Resend token in the same dialog sends it again.
  • Notion can't reach localhost. To test on your machine, run hookdeck listen 3000 notion --path /webhooks/notion and use the URL the Hookdeck CLI prints. Then change a page title and wait a minute or two for page.content_updated, or add a comment for comment.created within seconds.
  • Add the connection to the pages you want events for, and turn on the comment read capability for comment events. Notion's docs describe no way to resend a delivery, so log what you receive.

Delivery behaviour

  1. No events after creating a subscription

    A subscription delivers nothing until it's verified. Copy the verification_token Notion POSTs to your URL into the Verify dialog in the Webhooks tab, and check that the connection has access to the page that changed.

    Test your subscription →
  2. Out-of-order or stale events

    Notion says events may arrive out of order and may not show the current state. Use timestamp to reorder them, and fetch the entity from the API rather than trusting the event alone.

    Handle ordering →
  3. An edit produces one event, or none

    Notion aggregates events such as page.content_updated, so several edits can arrive as one event. If page.created and page.deleted happen in quick succession, you may get only one of them, or nothing.

    Plan for aggregation →
  4. Events missed during a long outage

    Notion retries up to 8 times, and the final attempt comes about 24 hours after the event. Its docs describe no resend, so reconcile from the API after a longer outage.

    Retries and recovery →

Notion webhook best practices

  • Verify every signature. Check X-Notion-Signature against the raw body, using the verification_token as the key. Without it, anyone who finds your URL can send fake events.
  • Fetch the latest state from the API. Events carry IDs, and Notion warns they may not show the current state. Use entity.id to fetch the content, and order by timestamp if you need to.
  • Respond first, then fetch. Notion documents no timeout, so return a 200 straight away and make your API calls from a queue.
  • Make handlers idempotent. Notion aims for at-most-once delivery, but a retry can repeat work. Record the event id and make your handler safe to run twice.
  • Plan for aggregated events. Use each event as a prompt to read current state, not as a record of each edit. A quick create and delete can produce no event at all.
  • Reconcile after an outage. Retries stop about 24 hours after the event and Notion's docs describe no resend, so read what changed from the API.

Common Notion webhook events

Pages

page.content_updated Page content changes, such as a block added or removed
page.properties_updated A property value on a page changes
page.created New page appears where your connection has access

Data sources

data_source.content_updated Data source content changes, such as a child page added
data_source.schema_updated Data source properties added, changed or removed
data_source.created Data source added to an existing database

Comments

comment.created Comment or suggested edit added to a page or block
comment.updated Comment edited, or its attached file finishes uploading
comment.deleted Comment is removed

Events by resource

Resource Events Payloads
page

page.content_updated · .properties_updated · .created · .deleted +5

9 8
data_source

data_source.created · .content_updated · .schema_updated · .deleted +2

6 6
database

database.created · .schema_updated · .content_updated · .deleted +2

6 6
file_upload

file_upload.created · .completed · .expired · .upload_failed

4 0
comment

comment.created · .updated · .deleted

3 3
view

view.created · .updated · .deleted

3 0

All 31 events →

In this hub

Webhook events → Every covered Notion event, with payloads where the registry has them.
MCP events → How an agent subscribes to Notion events as MCP events.
Verify signatures → Signature facts, verification code and common failures.
Production guide → Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
Agent skill → Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill notion-webhooks

Keep a long outage from losing your Notion events.

Hookdeck Event Gateway accepts every Notion delivery, verifies its signature, queues events and retries to your service on your schedule, and you can change where events go without recreating the subscription.

Not affiliated with Notion. Facts are compiled from public sources and linked inline.