Dosu Logo
Home
You are currently viewing an archived version of a document, the data may be outdated.
Documents
Notion Database Webhook Sync
Notion Database Webhook Sync
Type
Document
Status
Published
Created
Dec 12, 2025
Updated
Dec 15, 2025
Created by
Dosu Bot
Updated by
Dosu Bot

Notion Database Webhook Sync#

Dosu supports real-time synchronization of Notion databases using webhook events. When changes occur in your Notion workspace—such as creating, updating, deleting, or undeleting a database—Dosu automatically updates its internal state to reflect these changes. This ensures your Dosu environment always mirrors the current structure and content of your Notion databases.

Supported Notion Database Events#

Dosu listens for the following Notion database events, forwarded via Nango:

  • database.created
  • database.content_updated
  • database.properties_updated
  • database.undeleted
  • database.deleted
  • Data source events referencing databases (e.g., data_source.created, data_source.content_updated, data_source.schema_updated, data_source.deleted)

How It Works#

1. Webhook Reception#

When a supported Notion event occurs, Nango forwards the webhook to Dosu’s public API. Dosu parses the event and verifies that the workspace has an active Notion data source. If no data source is found, the event is ignored.

2. Workflow Enqueuing#

For valid events, Dosu enqueues a workflow to process the event. All workflows are partitioned by workspace ID, ensuring that events for different workspaces are processed independently and efficiently.

3. Database Synchronization or Deletion#

Depending on the event type:

  • Sync Events (created, content_updated, properties_updated, undeleted, and relevant data source events):

    • Dosu fetches the latest database details from the Notion API.
    • The database is upserted (created or updated) in Dosu’s internal state.
    • Parent database relationships are preserved, ensuring data source events remain correctly associated with their parent databases.

  • Delete Events (database.deleted):

    • Dosu removes the database from its internal state.
    • If the database does not exist, the event is logged and ignored.

4. Real-Time Reflection#

All changes are processed in real time, so your Dosu workspace always reflects the current state of your Notion databases, including structure, properties, and relationships.

Data Source and Parent Database Handling#

For data source events, Dosu uses the parent database ID provided in the event payload to ensure updates are correctly linked to their parent databases. This maintains the integrity of relationships within your workspace.

Example Workflow#

handle = enqueue_workflow(
    sync_notion_database_from_webhook,
    DATA_SYNC_QUEUE,
    options={"queue_partition_key": str(workspace_id)},
    workspace_id=workspace_id,
    database_external_id=entity_id,
)

Sequence Overview#

Benefits#

  • Real-time updates: Dosu instantly reflects changes made in Notion databases.
  • Multi-tenant isolation: Events are processed independently per workspace for reliability and scalability.
  • Relationship integrity: Parent-child relationships between data sources and databases are preserved.

Troubleshooting#

  • If your Notion database changes are not reflected in Dosu, ensure your workspace has an active Notion data source connection.
  • Only the supported event types listed above will trigger updates in Dosu.

For more details, refer to your workspace’s integration settings or contact support.