fix(notion): align webhook lifecycle and outputs

Handle Notion verification requests safely, expose the documented webhook fields in the trigger contract, and update setup guidance so runtime data and user-facing configuration stay aligned.

Made-with: Cursor

Author: waleedlatif1

apps/sim/lib/webhooks/providers/notion.ts

@@ -53,21 +53,59 @@ export const notionHandler: WebhookProviderHandler = {
     providerLabel: 'Notion',
   }),
 
+  handleReachabilityTest(body: unknown, requestId: string) {
+    const obj = body as Record<string, unknown> | null
+    const verificationToken = obj?.verification_token
+
+    if (typeof verificationToken === 'string' && verificationToken.length > 0) {
+      logger.info(`[${requestId}] Notion verification request detected - returning 200`)
+      return NextResponse.json({
+        status: 'ok',
+        message: 'Webhook endpoint verified',
+      })
+    }
+
+    return null
+  },
+
   async formatInput({ body }: FormatInputContext): Promise<FormatInputResult> {
     const b = body as Record<string, unknown>
+    const rawEntity =
+      b.entity && typeof b.entity === 'object' ? (b.entity as Record<string, unknown>) : {}
+    const rawData = b.data && typeof b.data === 'object' ? (b.data as Record<string, unknown>) : {}
+    const rawParent =
+      rawData.parent && typeof rawData.parent === 'object'
+        ? (rawData.parent as Record<string, unknown>)
+        : null
+
     return {
       input: {
         id: b.id,
         type: b.type,
         timestamp: b.timestamp,
+        api_version: b.api_version,
         workspace_id: b.workspace_id,
         workspace_name: b.workspace_name,
         subscription_id: b.subscription_id,
         integration_id: b.integration_id,
         attempt_number: b.attempt_number,
         authors: b.authors || [],
-        entity: b.entity || {},
-        data: b.data || {},
+        accessible_by: b.accessible_by || [],
+        entity: {
+          ...rawEntity,
+          entity_type: rawEntity.type,
+        },
+        data: {
+          ...rawData,
+          ...(rawParent
+            ? {
+                parent: {
+                  ...rawParent,
+                  parent_type: rawParent.type,
+                },
+              }
+            : {}),
+        },
       },
     }
   },

apps/sim/triggers/notion/utils.ts

@@ -32,6 +32,14 @@ export function notionSetupInstructions(eventType: string): string {
     'Ensure the integration has access to the pages/databases you want to monitor (share them with the integration).',
   ]
 
+  if (eventType === 'comment.created') {
+    instructions.splice(
+      7,
+      0,
+      'Enable the <strong>comment read</strong> capability in your Notion integration settings so comment events can be delivered.'
+    )
+  }
+
   return instructions
     .map(
       (instruction, index) =>
@@ -71,11 +79,16 @@ function buildBaseOutputs(): Record<string, TriggerOutput> {
       description: 'Event type (e.g., page.created, database.schema_updated)',
     },
     timestamp: { type: 'string', description: 'ISO 8601 timestamp of the event' },
+    api_version: { type: 'string', description: 'Notion API version included with the event' },
     workspace_id: { type: 'string', description: 'Workspace ID where the event occurred' },
     workspace_name: { type: 'string', description: 'Workspace name' },
     subscription_id: { type: 'string', description: 'Webhook subscription ID' },
     integration_id: { type: 'string', description: 'Integration ID that received the event' },
     attempt_number: { type: 'number', description: 'Delivery attempt number' },
+    accessible_by: {
+      type: 'array',
+      description: 'Array of users and bots that can access the entity',
+    },
   }
 }
 
@@ -85,7 +98,7 @@ function buildBaseOutputs(): Record<string, TriggerOutput> {
 function buildEntityOutputs(): Record<string, TriggerOutput> {
   return {
     id: { type: 'string', description: 'Entity ID (page or database ID)' },
-    entity_type: { type: 'string', description: 'Entity type (page or database)' },
+    entity_type: { type: 'string', description: 'Entity type (page, database, block, or comment)' },
   }
 }
 
@@ -101,9 +114,20 @@ export function buildPageEventOutputs(): Record<string, TriggerOutput> {
     },
     entity: buildEntityOutputs(),
     data: {
+      updated_blocks: {
+        type: 'array',
+        description: 'Blocks updated as part of the event, when provided by Notion',
+      },
+      updated_properties: {
+        type: 'array',
+        description: 'Property IDs updated as part of the event, when provided by Notion',
+      },
       parent: {
         id: { type: 'string', description: 'Parent page or database ID' },
-        parent_type: { type: 'string', description: 'Parent type (database, page, workspace)' },
+        parent_type: {
+          type: 'string',
+          description: 'Parent type (database, page, block, or workspace)',
+        },
       },
     },
   }
@@ -121,9 +145,17 @@ export function buildDatabaseEventOutputs(): Record<string, TriggerOutput> {
     },
     entity: buildEntityOutputs(),
     data: {
+      updated_blocks: {
+        type: 'array',
+        description: 'Blocks updated as part of the event, when provided by Notion',
+      },
+      updated_properties: {
+        type: 'array',
+        description: 'Database properties updated as part of the event, when provided by Notion',
+      },
       parent: {
         id: { type: 'string', description: 'Parent page or workspace ID' },
-        parent_type: { type: 'string', description: 'Parent type (page, workspace)' },
+        parent_type: { type: 'string', description: 'Parent type (page, database, or workspace)' },
       },
     },
   }
@@ -144,9 +176,10 @@ export function buildCommentEventOutputs(): Record<string, TriggerOutput> {
       entity_type: { type: 'string', description: 'Entity type (comment)' },
     },
     data: {
+      page_id: { type: 'string', description: 'Page ID that owns the comment thread' },
       parent: {
-        id: { type: 'string', description: 'Parent page ID' },
-        parent_type: { type: 'string', description: 'Parent type (page)' },
+        id: { type: 'string', description: 'Parent page or block ID' },
+        parent_type: { type: 'string', description: 'Parent type (page or block)' },
       },
     },
   }
@@ -164,8 +197,22 @@ export function buildGenericWebhookOutputs(): Record<string, TriggerOutput> {
     },
     entity: buildEntityOutputs(),
     data: {
-      type: 'json',
-      description: 'Event-specific data including parent information',
+      parent: {
+        id: { type: 'string', description: 'Parent entity ID, when provided by Notion' },
+        parent_type: {
+          type: 'string',
+          description: 'Parent entity type (page, database, block, or workspace), when present',
+        },
+      },
+      page_id: { type: 'string', description: 'Page ID related to the event, when present' },
+      updated_blocks: {
+        type: 'array',
+        description: 'Blocks updated as part of the event, when provided by Notion',
+      },
+      updated_properties: {
+        type: 'array',
+        description: 'Updated properties included with the event, when provided by Notion',
+      },
     },
   }
 }