Notion webhooks in production: duplicates, ordering, retries and timeouts
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. What Notion sends and how it's signed is on the Notion webhooks overview, every event type is on Notion webhook events, and signature verification code is on Verify Notion webhooks.
At a glance
| Problem | What to do | With Event Gateway |
|---|---|---|
| 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 | Record the event id; make handlers idempotent | Drops repeats before they reach your handler |
| 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 | Stay available; log what you receive; reconcile from the API | Accepts deliveries while your service is down and replays them |
| Choosing events | Subscribe to what you process; treat aggregated events as prompts to read state | Filters and routes events by type |
| Testing | Complete the handshake, then trigger real changes | Forwards to localhost and replays past events |
| 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
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:
- Verify the signature and return 200 straight away.
- Push the event onto a queue and make your API calls from a worker. See why to process webhooks asynchronously.
- 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
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:
- Track processed event
idvalues, using a database table with a unique constraint. Keep them for longer than the 24 hours or so that retries can last. - Make every handler idempotent: the same result however many times it runs. Log
attempt_numbertoo, so you can tell a retry from a second event for the same entity. - Wrap the side effect and the record of it in one transaction.
With Event Gateway: Hookdeck deduplicates 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
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.
Fix it in your handler:
- Use
entity.idfrom the event to fetch the page, database or comment from the API. - Store each entity's latest
timestamp, and skip work for an event older than the one you've already processed. - 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.
- Iterate over
data.updated_blocksanddata.updated_propertiesrather than assuming one change. Inpage.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.
Notion webhook retries and recovery
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:
- Run the endpoint on high-availability infrastructure, and return an error for a real failure so that Notion retries.
- Log every delivery with its
id,type,timestampandattempt_number, since Notion's docs describe no log of their own. Alert whenattempt_numberclimbs. - Check the subscription's status in the Webhooks tab after an incident. Nothing is delivered while it's paused or pending verification.
- 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 automatically, manually or in bulk once you recover.
Choosing which Notion events to listen to
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.
Fix it in your handler:
- List the event types your code handles and subscribe to exactly those in the Webhooks tab. You can change them at any time.
- 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.
- Use
comment.*,page.lockedandpage.unlockedwhere a delay matters. - Ignore types your handler doesn't expect, and still return 200, because new ones can appear.
With Event Gateway: Hookdeck filters and routes events by type, so one Notion subscription can feed several services.
Testing and debugging Notion webhooks locally
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:
- 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.
- 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 usingentity.id. - Add a comment for
comment.created, which should arrive within seconds. It needs thecomment readcapability in the connection's settings. - If nothing arrives, check that the connection has access to that page and that the subscription is active.
- Use
signWebhookPayload()from@notionhq/clientto sign fixtures for tests without a live subscription.
With Event Gateway: The Hookdeck 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 for a walk-through.
Other Notion webhook 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.
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_ and data_, and adds data.parent.data_. 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 records those changes.
The Send webhook action is a different feature. The action 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 you set, which keeps follow-up API calls under Notion's limits.
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.