# Notion webhooks in production: duplicates, ordering, retries and timeouts

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

This guide covers the problems Notion webhooks cause in production and how to handle each one. It's about connection webhooks, which Notion's older pages call integration webhooks, and not the no-code [Send webhook action](#other-limits). What Notion sends and how it's signed is on the [Notion webhooks](/webhooks/notion) overview, every event type is on [Notion webhook events](/webhooks/notion/events), and signature verification code is on [Verify Notion webhooks](/webhooks/notion/verify).

## At a glance

| Problem | What to do | With Event Gateway |
| --- | --- | --- |
| [Timeouts](#timeouts) | Return a 200 first; make your API calls from a background job | Accepts the delivery at once, then queues it for your service |
| [Duplicates](#duplicates) | Record the event `id`; make handlers idempotent | Drops repeats before they reach your handler |
| [Ordering](#ordering) | Reorder by `timestamp`; fetch the latest state from the API | Logs every event and attempt, so you can see arrival order when debugging |
| [Retries](#retries) | Stay available; log what you receive; reconcile from the API | Accepts deliveries while your service is down and replays them |
| [Choosing events](#choosing-events) | Subscribe to what you process; treat aggregated events as prompts to read state | Filters and routes events by type |
| [Testing](#testing) | Complete the handshake, then trigger real changes | Forwards to localhost and replays past events |
| [Other limits](#other-limits) | Plan for API rate limits, the locked URL, access and API versions | Holds events in a queue and delivers them at a rate you set |

## Notion webhook timeouts and slow handlers {#timeouts}

Notion's docs don't give a timeout, so return a 200 as soon as you've verified the signature and do the rest in a background job.

**Why it happens:** Notion retries when your endpoint fails to acknowledge an event, and its API reference says to return a 200 to show the data was received. Its docs don't say how long it waits, or how it treats other 2xx codes. Thin events make a slow handler more likely, because a handler that fetches from the API before responding depends on the speed of that call and on Notion's rate limits.

**Fix it in your handler:**

1. Verify the signature and return 200 straight away.
2. Push the event onto a queue and make your API calls from a worker. See [why to process webhooks asynchronously](/webhooks/guides/why-implement-asynchronous-processing-webhooks).
3. Alert on the worker's backlog, so that slow API calls don't go unnoticed.

**With Event Gateway:** Hookdeck accepts each Notion delivery immediately, then queues events and delivers them to your service at a rate you set, with its own retries. Your handler can take as long as it needs to fetch from Notion.

## Duplicate Notion webhooks {#duplicates}

Notion aims for at-most-once delivery, but it also retries, so make your handler safe to run twice. Use the event `id` as your key.

**Why it happens:** If your handler finishes the work but doesn't acknowledge in time, Notion can send the event again. The body's `attempt_number` shows which attempt you're looking at. Notion's docs describe `id` as the event's unique ID, but they don't state that a retry keeps it. Because Notion's events tell you to read current state, handling one twice usually costs an extra API call rather than bad data, unless your handler also has side effects.

**Fix it in your handler:**

1. Track processed event `id` values, using a database table with a unique constraint. Keep them for longer than the 24 hours or so that retries can last.
2. Make every handler [idempotent](/webhooks/guides/implement-webhook-idempotency): the same result however many times it runs. Log `attempt_number` too, so you can tell a retry from a second event for the same entity.
3. Wrap the side effect and the record of it in one transaction.

**With Event Gateway:** Hookdeck [deduplicates](/docs/deduplication) events before they reach your endpoint, so repeats are filtered at the infrastructure level rather than in each handler.

## Out-of-order and stale Notion webhooks {#ordering}

Events may arrive in a different order than they happened, and an event may not show the current state. Reorder by `timestamp` if order matters, and fetch the latest data from the API.

**Why it happens:** Notion's docs give no ordering guarantee and strongly recommend fetching the latest data. Retries can arrive long after newer events for the same entity, and aggregation delays some events but not others. Events are also thin: they give IDs and metadata, with no page content, property values or comment text. For more on the pattern, see [what thin events are](/webhooks/guides/what-are-thin-events).

**Fix it in your handler:**

1. Use `entity.id` from the event to fetch the page, database or comment from the API.
2. Store each entity's latest `timestamp`, and skip work for an event older than the one you've already processed.
3. Handle a fetch that returns something unexpected. The entity may have moved to the trash, or the connection may have lost access, since the event was sent.
4. Iterate over `data.updated_blocks` and `data.updated_properties` rather than assuming one change. In `page.properties_updated`, the list holds property IDs.

**With Event Gateway:** Hookdeck logs every event and delivery attempt, so when state looks wrong you can see the order events actually arrived in and replay them. For throttled fetching, see [handling thin events](/docs/guides/handling-thin-events-with-hookdeck).

## Notion webhook retries and recovery {#retries}

Notion retries a failed delivery up to 8 times with exponential backoff, and the final attempt comes about 24 hours after the event. Its docs describe no way to resend after that.

**Why it happens:** The retries cover a short outage. Notion's docs describe no delivery log and no manual resend, so if your endpoint stays down for longer, you have no list of what was missed. Notion doesn't publish the backoff schedule. The body's `attempt_number` runs from 1 to 8, so the total may be 8 deliveries rather than 8 retries on top of the first.

**Fix it in your handler:**

1. Run the endpoint on high-availability infrastructure, and return an error for a real failure so that Notion retries.
2. Log every delivery with its `id`, `type`, `timestamp` and `attempt_number`, since Notion's docs describe no log of their own. Alert when `attempt_number` climbs.
3. Check the subscription's status in the Webhooks tab after an incident. Nothing is delivered while it's paused or pending verification.
4. After an outage, read what changed from the API. A periodic sync also catches anything webhooks missed.

**With Event Gateway:** Hookdeck captures every Notion delivery while your services are down, so Notion's deliveries succeed. Failed events can be [retried](/docs/retries) automatically, manually or in bulk once you recover.

## Choosing which Notion events to listen to {#choosing-events}

Subscribe only to the event types you process, and treat aggregated events as prompts to read current state, not as a record of each edit.

**Why it matters:** Each event you handle usually means at least one API call, so extra event types spend your rate limit. Most events are aggregated: Notion batches changes to one entity within a short window, which adds a short delay, typically under a minute. If `page.created`, `page.deleted` and `page.undeleted` happen in quick succession, you may receive only the most meaningful one, or nothing if the page ends up as it started. `comment.*`, `page.locked` and `page.unlocked` aren't aggregated. Subscriptions also don't pick up new event types automatically. The full list, with sample payloads where Notion publishes them, is on [Notion webhook events](/webhooks/notion/events).

**Fix it in your handler:**

1. List the event types your code handles and subscribe to exactly those in the Webhooks tab. You can change them at any time.
2. Don't count aggregated events as edits, or expect a short-lived change to produce an event. If you need every change, webhooks alone won't give it to you.
3. Use `comment.*`, `page.locked` and `page.unlocked` where a delay matters.
4. Ignore types your handler doesn't expect, and still return 200, because new ones can appear.

**With Event Gateway:** Hookdeck [filters](/docs/filters) and routes events by type, so one Notion subscription can feed several services.

## Testing and debugging Notion webhooks locally {#testing}

Complete the handshake against a public URL, then make real changes in Notion. Your endpoint gets nothing until the subscription is verified.

**Why it happens:** Notion can't reach localhost, and it sends one `verification_token` to your URL when you create the subscription. Until someone pastes that token into the Verify dialog in the Webhooks tab, no events are sent. Its docs describe no test delivery, so you trigger events by making changes. Aggregated events take a minute or two to arrive, which can look like a broken setup.

**Fix it in your handler:**

1. Log the body of the first request so that you can copy the token. If you missed it, click Resend token in the Verify dialog. Notion's docs don't say whether this request is signed, and you don't have the key yet, so handle it before your signature check.
2. Add the connection to a page and change the page's title. Wait a minute or two for `page.content_updated`, then fetch the page using `entity.id`.
3. Add a comment for `comment.created`, which should arrive within seconds. It needs the `comment read` capability in the connection's settings.
4. If nothing arrives, check that the connection has access to that page and that the subscription is active.
5. Use `signWebhookPayload()` from `@notionhq/client` to sign fixtures for tests without a live subscription.

**With Event Gateway:** The [Hookdeck CLI](/docs/cli) gives you a stable URL that sends webhooks to your machine: run `hookdeck listen 3000 notion --path /webhooks/notion`, take the token from the first request, then replay past events with one click. See [how to test and replay Notion webhooks locally](/webhooks/platforms/how-to-test-and-replay-notion-webhooks-locally-with-hookdeck) for a walk-through.

## Other Notion webhook limits {#other-limits}

Plan for API rate limits, the locked URL, access rules and API versions before they reach production.

**API rate limits.** Thin events mean follow-up calls. Each connection gets 180 requests a minute, an average of 3 a second, or 600 a minute on Business and Enterprise plans. A separate limit is shared across a workspace's connections, and querying a data source has its own limit of about 3 requests a second. Over a limit, Notion returns a 429 with a `Retry-After` header. Queue your calls, combine events for the same entity, and wait as long as `Retry-After` says. See Notion's [request limits](https://developers.notion.com/reference/request-limits).

**The URL locks at verification.** You can change a subscription's event types at any time, but after verification, changing its URL means deleting and recreating it, which sends a new token. Point it at a URL you control.

**Events depend on access.** A connection only gets events for content it can access. If a page is created inside a private page the connection can't see, no event fires. Check coverage when people add new pages or databases.

**API versions.** 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.content_updated` and `data_source.schema_updated`, and adds `data.parent.data_source_id`. Make your handler accept both shapes before you upgrade. `2026-03-11` changes no webhook payload.

**No events for people or settings.** The event list has nothing for members, permissions or workspace settings. On Enterprise plans, the [audit log](https://www.notion.com/help/audit-log) records those changes.

**The Send webhook action is a different feature.** The [action](https://www.notion.com/help/webhook-actions) in buttons and database automations is on paid plans and allows up to five webhooks per automation, POST only. In a database automation it can send the properties you pick, and if it fails, the automation pauses until you resume it.

**With Event Gateway:** Hookdeck gives Notion one stable URL to deliver to, so you can change where events go without recreating the subscription. It holds events in a queue and delivers them at a [max delivery rate](/docs/destinations#set-a-max-delivery-rate) you set, which keeps follow-up API calls under Notion's limits.