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.
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
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.
{raw body} The request body exactly as sent, with nothing added. No timestamp is added to the signed content.
id, timestamp, workspace_id, workspace_name, subscription_id, integration_id, type, authors, accessible_by, attempt_number, api_version, entity, data 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_tokento 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/notionand use the URL the Hookdeck CLI prints. Then change a page title and wait a minute or two forpage.content_updated, or add a comment forcomment.createdwithin seconds. - Add the connection to the pages you want events for, and turn on the
comment readcapability for comment events. Notion's docs describe no way to resend a delivery, so log what you receive.
Delivery behaviour
not documented acknowledge receipt with a 200 before doing the work Retries up to 8 with exponential backoff, the last about 24 hours after the event After retries no resend documented read what changed from the API, using your own log to find the gap Ordering not guaranteed reorder by timestamp, or fetch the latest state Known failure modes
From Hookdeck's Notion guide →-
No events after creating a subscription
A subscription delivers nothing until it's verified. Copy the
Test your subscription →verification_tokenNotion POSTs to your URL into the Verify dialog in the Webhooks tab, and check that the connection has access to the page that changed. -
Out-of-order or stale events
Notion says events may arrive out of order and may not show the current state. Use
Handle ordering →timestampto reorder them, and fetch the entity from the API rather than trusting the event alone. -
An edit produces one event, or none
Notion aggregates events such as
Plan for aggregation →page.content_updated, so several edits can arrive as one event. Ifpage.createdandpage.deletedhappen in quick succession, you may get only one of them, or nothing. -
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-Signatureagainst the raw body, using theverification_tokenas 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.idto fetch the content, and order bytimestampif 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
idand 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 | 9 | 8 |
data_source | 6 | 6 |
database | 6 | 6 |
file_upload | 4 | 0 |
comment | 3 | 3 |
view | 3 | 0 |
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.