Notion API Webhooks Support in 2026: What Changed and How to Use It

For years, the most common complaint about the Notion API was the lack of webhooks. If you wanted to react to changes in a Notion database, you had to poll the API on a timer, compare snapshots, and hope your rate limit budget held up. In January 2026, Notion shipped webhook support for automations, and in March they expanded webhook capabilities in the REST API. This post covers both systems, how they work, and when to use each one.

The Two Webhook Systems

Notion now offers two distinct ways to receive real-time notifications from workspace events. They serve different use cases and have different setup requirements.

| Feature | Automation Webhooks | API Webhooks (Beta) | |---|---|---| | Announced | January 2026 | March 2026 (API v2026-03-01) | | Setup | Notion UI, no code | REST API registration | | Trigger scope | Single database events | Workspace-wide or page-level | | Payload format | Configurable template | Standardized JSON | | Authentication | None (URL receives POST) | HMAC-SHA256 signature | | Rate limits | 1 webhook per automation step | 50 webhook subscriptions per integration | | Retry policy | 3 retries over 1 hour | Exponential backoff, 24h window | | Ideal for | No-code workflows, Zapier-style triggers | Custom integrations, production systems |

Automation Webhooks (January 2026)

Automation webhooks were the first webhook capability Notion shipped. They work as an action step inside Notion's database automation system.

How They Work

1. Create an automation on a database (trigger: property change, new page, etc.)
2. Add a "Send webhook" action step
3. Configure the endpoint URL, HTTP method, headers, and payload template
4. The payload template supports dynamic property values from the triggering page

The payload template uses Notion's property reference syntax. A typical configuration looks like this:

{
  "event": "page_updated",
  "page_id": "{{page.id}}",
  "title": "{{page.Title}}",
  "status": "{{page.Status}}",
  "assigned_to": "{{page.Assigned To.email}}",
  "updated_at": "{{automation.triggered_at}}"
}

Limitations

Automation webhooks have a few constraints worth knowing before you build on them:

• No signature verification on the receiving end (you cannot confirm the request came from Notion)
• No built-in filtering beyond the automation trigger conditions
• The payload template editor has limited debugging (test sends are available but do not show error details)
• One webhook action per automation step (you can chain multiple steps to hit multiple endpoints)

API Webhooks (March 2026, Beta)

The REST API webhook system is the more robust option. It was announced alongside Notion API version 2026-03-01 and is currently in public beta.

Registration

You register a webhook subscription by calling the new /v1/webhooks endpoint:

curl -X POST https://api.notion.com/v1/webhooks \
  -H "Authorization: Bearer ntn_your_integration_token" \
  -H "Notion-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/notion-webhook",
    "events": ["page.updated", "page.created", "database.row_added"],
    "filter": {
      "database_id": "abc123..."
    }
  }'

Notion responds with a subscription object that includes a signing_secret for verifying incoming payloads.

Supported Events

The beta currently supports the following event types:

| Event | Description | |---|---| | page.created | A new page is added to the workspace or a specific database | | page.updated | Any property on a page changes | | page.deleted | A page is moved to trash | | database.row_added | A new row is added to a database | | database.schema_changed | A database property is added, removed, or renamed | | comment.created | A comment is added to a page or block |

Payload Structure

Every webhook delivery follows this structure:

{
  "id": "evt_abc123",
  "type": "page.updated",
  "timestamp": "2026-04-10T14:30:00.000Z",
  "workspace_id": "ws_def456",
  "data": {
    "page_id": "pg_789",
    "parent": {
      "type": "database_id",
      "database_id": "db_012"
    },
    "properties_changed": ["Status", "Assigned To"],
    "last_edited_by": {
      "id": "user_345",
      "name": "Matthew Diakonov"
    }
  },
  "subscription_id": "wh_sub_678"
}

Signature Verification

Every webhook request includes an X-Notion-Signature header containing an HMAC-SHA256 hash of the raw request body, signed with your subscription's signing_secret. Always verify this before processing the payload.

import hmac
import hashlib

def verify_notion_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Architecture: Before and After Webhooks

The following diagram shows how Notion integrations worked before webhooks (polling) compared to the two webhook approaches available in 2026.

Migrating from Polling to Webhooks

If you have an existing integration that polls Notion databases, here is a practical migration path:

Step 1: Register webhook subscriptions for your target databases

Keep your polling running in parallel during the transition. Register webhooks for the events you care about and log incoming payloads without acting on them yet.

Step 2: Compare webhook events against poll results

Run both systems for a few days. Confirm that webhook events arrive for every change your polling system detects. Watch for edge cases: bulk imports, API-driven updates, and property changes made by automations.

Step 3: Switch processing to webhook-driven

Once you trust the webhook delivery, route your processing logic to the webhook handler. Keep polling as a fallback that runs every 5 to 10 minutes to catch any missed events.

Step 4: Reduce polling frequency

After a week of stable webhook delivery, drop polling to once per hour or remove it entirely. Many production integrations keep a low-frequency poll as a safety net.

Common Patterns

Syncing Notion to an External Database

Register a page.updated webhook filtered to your target database. On each delivery, fetch the full page object using the existing /v1/pages/{id} endpoint (the webhook payload includes the page ID but not all property values), then upsert into your external database.

Slack Notifications on Status Changes

Use an automation webhook if you want zero code. Set the trigger to "Status property changed," configure the webhook to POST to a Slack incoming webhook URL, and format the payload as a Slack message block.

For more control, use an API webhook with a page.updated event filter, check properties_changed for "Status" in your handler, then call the Slack API with a richer message.

Multi-step Workflows

Chain automation webhooks with tools like Make or n8n. The automation webhook fires on the Notion event, hits your workflow tool's webhook URL, and the workflow tool handles the downstream steps (updating a CRM, sending an email, creating a Jira ticket).

Limits and Quotas

| Resource | Limit | |---|---| | Webhook subscriptions per integration | 50 | | Events per webhook delivery | 1 (each event is a separate delivery) | | Payload size | 256 KB max | | Delivery timeout | 10 seconds (your server must respond within 10s) | | Retry window | 24 hours with exponential backoff | | Automation webhook endpoints per workspace | 100 |

What Is Still Missing

The webhook system is in beta, and a few gaps remain as of April 2026:

• Block-level changes: Webhooks fire on page property changes but not on content block edits (adding a paragraph, checking a to-do item). You still need polling for content-level sync.
• Batch subscriptions: You cannot subscribe to multiple databases in a single API call. Each database requires a separate subscription.
• Webhook management UI: There is no dashboard in Notion's settings to view or manage API webhook subscriptions. You manage them entirely through the API.
• Historical replay: If your server was down and missed events during the retry window, there is no way to replay them. You need a polling fallback for disaster recovery.

How This Connects to Desktop AI Agents

If you use a desktop AI agent that interacts with Notion through the accessibility layer or API, webhooks open a new interaction pattern. Instead of the agent polling Notion on a timer, your server can receive webhook events and forward them to the agent as triggers. A status change in a Notion project tracker can automatically prompt the agent to update a local dashboard, send a summary, or kick off a related task, all without the agent burning API calls on polling.

This is particularly relevant for tools like Fazm that run locally and react to workspace events. The combination of Notion webhooks and a local AI agent creates a responsive loop where workspace changes translate into desktop actions within seconds.

Summary

Notion API webhooks support in 2026 comes in two forms: automation webhooks for no-code triggers and API webhooks for production integrations. The automation version shipped in January, the API version in March. Together, they eliminate the biggest pain point of building on the Notion platform. If you are starting a new Notion integration today, build on webhooks from the start. If you have an existing polling-based system, migrate incrementally and keep a low-frequency poll as a safety net until the beta stabilizes.