# 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](https://www.notion.com/help/webhook-actions) 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.

Agent skill: `npx skills add hookdeck/webhook-skills --skill notion-webhooks` ([details](https://hookdeck.com/webhooks/notion/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [Notion's official docs](https://developers.notion.com/reference/webhooks-events-delivery).

[Overview](https://hookdeck.com/webhooks/notion) · [Webhook events (31)](https://hookdeck.com/webhooks/notion/events) · [MCP events](https://hookdeck.com/webhooks/notion/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/notion/verify) · [Production guide](https://hookdeck.com/webhooks/notion/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/notion/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `X-Notion-Signature` Format: sha256=<hex> | [Notion docs](https://developers.notion.com/reference/webhooks) |
| 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](https://developers.notion.com/reference/webhooks)) | [Notion docs](https://developers.notion.com/reference/webhooks) |
| Signed material | `{raw body}` The request body exactly as sent, with nothing added. No timestamp is added to the signed content. | [Notion docs](https://developers.notion.com/reference/webhooks) |
| How events are identified | `type field in the body` | [Notion docs](https://developers.notion.com/reference/webhooks-events-delivery) |
| Body format | `JSON` Content type: application/json. | [Notion docs](https://developers.notion.com/reference/webhooks) |
| API versioning | `api_version in the body` Seen: 2022-06-28, 2025-09-03, 2026-03-11. | [Notion docs](https://developers.notion.com/openapi.json) |
| Envelope | `id, timestamp, workspace_id, workspace_name, subscription_id, integration_id, type, authors, accessible_by, attempt_number, api_version, entity, data` | [Notion docs](https://developers.notion.com/reference/webhooks-events-delivery) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill notion-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/notion/skill) |

[Verify Notion webhooks](https://hookdeck.com/webhooks/notion/verify)

## 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.

## Setting up Notion webhooks

- Create a subscription in the Webhooks tab of your [connection settings](https://app.notion.com/developers/connections), 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

- **Timeout:** not documented. acknowledge receipt with a 200 before doing the work. [Guide](https://hookdeck.com/webhooks/notion/guide-duplicates-ordering-retries-timeouts#timeouts)
- **Retries:** up to 8. with exponential backoff, the last about 24 hours after the event. [Guide](https://hookdeck.com/webhooks/notion/guide-duplicates-ordering-retries-timeouts#retries)
- **After retries:** no resend documented. read what changed from the API, using your own log to find the gap. [Guide](https://hookdeck.com/webhooks/notion/guide-duplicates-ordering-retries-timeouts#retries)
- **Ordering:** not guaranteed. reorder by `timestamp`, or fetch the latest state. [Guide](https://hookdeck.com/webhooks/notion/guide-duplicates-ordering-retries-timeouts#ordering)

## Known failure modes

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](https://hookdeck.com/webhooks/notion/guide-duplicates-ordering-retries-timeouts#testing)
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](https://hookdeck.com/webhooks/notion/guide-duplicates-ordering-retries-timeouts#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](https://hookdeck.com/webhooks/notion/guide-duplicates-ordering-retries-timeouts#choosing-events)
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](https://hookdeck.com/webhooks/notion/guide-duplicates-ordering-retries-timeouts#retries)

From [Hookdeck's Notion guide](https://hookdeck.com/webhooks/notion/guide-duplicates-ordering-retries-timeouts).

## Notion webhook best practices

- **[Verify every signature](https://hookdeck.com/webhooks/notion/verify).** 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](https://hookdeck.com/webhooks/notion/guide-duplicates-ordering-retries-timeouts#ordering).** 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](https://hookdeck.com/webhooks/notion/guide-duplicates-ordering-retries-timeouts#timeouts).** Notion documents no timeout, so return a 200 straight away and make your API calls from a queue.
- **[Make handlers idempotent](https://hookdeck.com/webhooks/notion/guide-duplicates-ordering-retries-timeouts#duplicates).** 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](https://hookdeck.com/webhooks/notion/guide-duplicates-ordering-retries-timeouts#choosing-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](https://hookdeck.com/webhooks/notion/guide-duplicates-ordering-retries-timeouts#retries).** 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](https://hookdeck.com/webhooks/notion/events#page.content_updated): Page content changes, such as a block added or removed
- [page.properties_updated](https://hookdeck.com/webhooks/notion/events#page.properties_updated): A property value on a page changes
- [page.created](https://hookdeck.com/webhooks/notion/events#page.created): New page appears where your connection has access

### Data sources

- [data_source.content_updated](https://hookdeck.com/webhooks/notion/events#data_source.content_updated): Data source content changes, such as a child page added
- [data_source.schema_updated](https://hookdeck.com/webhooks/notion/events#data_source.schema_updated): Data source properties added, changed or removed
- [data_source.created](https://hookdeck.com/webhooks/notion/events#data_source.created): Data source added to an existing database

### Comments

- [comment.created](https://hookdeck.com/webhooks/notion/events#comment.created): Comment or suggested edit added to a page or block
- [comment.updated](https://hookdeck.com/webhooks/notion/events#comment.updated): Comment edited, or its attached file finishes uploading
- [comment.deleted](https://hookdeck.com/webhooks/notion/events#comment.deleted): Comment is removed

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [page](https://hookdeck.com/webhooks/notion/events#resource-page) | 9 | 8 |
| [data_source](https://hookdeck.com/webhooks/notion/events#resource-data-source) | 6 | 6 |
| [database](https://hookdeck.com/webhooks/notion/events#resource-database) | 6 | 6 |
| [file_upload](https://hookdeck.com/webhooks/notion/events#resource-file-upload) | 4 | 0 |
| [comment](https://hookdeck.com/webhooks/notion/events#resource-comment) | 3 | 3 |
| [view](https://hookdeck.com/webhooks/notion/events#resource-view) | 3 | 0 |

[All 31 events](https://hookdeck.com/webhooks/notion/events)

## In this hub

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

Not affiliated with Notion. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/notion.json) · [Report a correction](https://hookdeck.com/contact)
