Notion

Notion Connection

Put Notion to Work with @Human Automations and @Human Agents

The Notion Connection documents all Triggers, Actions and Query Operations available for creating automations via the Notion API.

What can you do with the Notion Connection?

• Connect to the Notion API in a few clicks

• Use the related Notion Operations (see below) in @Human Automations or @Human Agents

Related Operations

Trigger Operations

Database Created

Triggers on: databases/database.created

Triggered when a new database is created in Notion.

Database Updated

Triggers on: databases/database.updated

Triggered when an existing database is updated in Notion.

Page Created

Triggers on: pages/page.created

Triggered when a new page is created in Notion.

Page Updated

Triggers on: pages/page.updated

Triggered when an existing page is updated in Notion.

Block Updated

Triggers on: blocks/block.updated

Triggered when a block is updated in Notion.

User Updated

Triggers on: users/user.updated

Triggered when a user's information is updated in Notion.

Comment Created

Triggers on: comments/comment.created

Triggered when a new comment is created in Notion.

Action Operations

Action: Create a Database

Action: Update a Database

Action: Create a Page

Action: Update a Page

Query Operations

Query: Retrieve a Database

Query: Retrieve a Page

Related Automations

Example link

Obtaining Access Credentials

To obtain a Personal Access Token (PAT) for Notion's system-to-system integration, follow these steps:

Prerequisites

• A Notion account (free or paid).

• Access to the Notion workspace where the integration will be used.

Steps to Generate a Notion PAT

1. Log in to your Notion account at notion.so.

2. Click on your profile icon (top-right) → Settings.

3. Navigate to Connections.

4. Click on Develop or manage integrations.

   • If prompted, confirm you want to create a new integration.

5. Create a New Integration

6. Enter a name (e.g., "API Access").

7. Select the workspace where the integration will operate.

8. Click Create.

9. Click on Configure Integration Settings.

10. After creation, you’ll see a secret token under Internal Integration Secret.

11. Copy this token (treat it like a password—store securely).

    • This is your PAT for system-to-system access.

Configuring Webhooks

1. Log in to your Notion account at notion.so.

2. Click on your profile icon (top-right) → Settings.

3. Navigate to Connections.

4. Click on Develop or manage integrations.

5. Select the integration you wish to configure.

6. Click on the Webhooks tab in the sidebar.

7. Click + Create a subscription.

8. Enter your Webhook URL (must be a public HTTPS endpoint).

9. Select the event types you want to subscribe to (e.g., page updates, database changes).

10. Click Create subscription.

11. Copy the Signature Secret provided to verify incoming webhook payloads.

Code (Apache v2.0): Service Connectivity and Metadata

{
  "handle": "notion-api-v1",
  "status": "active",
  "meta": {
    "short": "Notion API",
    "description": "Connect to Notion's API to manage databases, pages, and more.",
    "icon": "notion",
    "tags": ["productivity", "database", "collaboration"]
  },
  "service": {
    "baseURL": {
      "value": "https://api.notion.com/v1"
    },
    "protocol": "https",
    "contentType": "application/json",
    "headers": {
      "Notion-Version": {
        "value": "2022-06-28"
      }
    },
    "auth": {
      "method": "api_token",
      "params": {
        "apiToken": {
          "token": {
            "value": "{{apiToken}}",
            "placeholders": [
              {
                "name": "apiToken",
                "type": "String",
                "description": "Notion API token for authentication.",
                "required": true
              }
            ]
          },
          "headerName": {
            "value": "Authorization"
          }
        }
      }
    }
  }
}

Code (Apache v2.0): List of External Resources and Internal Mapping

[
  {
    "handle": "databases",
    "meta": {
      "short": "Databases",
      "description": "Manage and query Notion databases"
    },
    "endpoint": {
      "value": "v1/databases"
    },
    "fields": [
      {
        "name": "id",
        "type": "String",
        "selector": [
          "id"
        ],
        "meta": {
          "description": "Unique identifier for the database"
        }
      },
      {
        "name": "title",
        "type": "String",
        "selector": [
          "title",
          0,
          "plain_text"
        ],
        "meta": {
          "description": "Title of the database"
        },
        "multivalue": true
      },
      {
        "name": "created_time",
        "type": "String",
        "selector": [
          "created_time"
        ],
        "meta": {
          "description": "ISO 8601 timestamp when the database was created."
        }
      },
      {
        "name": "last_edited_time",
        "type": "String",
        "selector": [
          "last_edited_time"
        ],
        "meta": {
          "description": "ISO 8601 timestamp when the database was last edited."
        }
      },
      {
        "name": "url",
        "type": "String",
        "selector": [
          "url"
        ],
        "meta": {
          "description": "The URL of the database in Notion."
        }
      }
    ],
    "operations": {
      "list": {
        "method": "GET",
        "path": {
          "value": ""
        },
        "headers": {
          "Notion-Version": "2022-06-28",
          "Authorization": "Bearer {{apiKey}}"
        }
      },
      "read": {
        "method": "GET",
        "path": {
          "value": "{{databaseId}}"
        },
        "headers": {
          "Notion-Version": "2022-06-28",
          "Authorization": "Bearer {{apiKey}}"
        }
      },
      "create": {
        "method": "POST",
        "path": {
          "value": ""
        },
        "headers": {
          "Notion-Version": "2022-06-28",
          "Authorization": "Bearer {{apiKey}}",
          "Content-Type": "application/json"
        },
        "bodyTemplate": {
          "value": "{\"parent\": {\"type\": \"{{parentType}}\", \"{{parentType}}\": \"{{parentId}}\"},\"title\": [{\"type\": \"text\", \"text\": {\"content\": \"{{title}}\"}}],\"properties\": {{properties}}}"
        }
      },
      "update": {
        "method": "PATCH",
        "path": {
          "value": "{{databaseId}}"
        },
        "headers": {
          "Notion-Version": "2022-06-28",
          "Authorization": "Bearer {{apiKey}}",
          "Content-Type": "application/json"
        },
        "bodyTemplate": {
          "value": "{\"title\": [{\"type\": \"text\", \"text\": {\"content\": \"{{title}}\"}}],\"properties\": {{properties}}}"
        }
      }
    },
    "webhooks": [
      {
        "event": "database.created",
        "path": "/webhooks/notion/database.created",
        "payload": [
          { "name": "id", "type": "String", "selector": ["id"], "meta": { "description": "The unique identifier for the database." } },
          { "name": "title", "type": "String", "selector": ["title", 0, "plain_text"], "meta": { "description": "The title of the database." } }
        ]
      },
      {
        "event": "database.updated",
        "path": "/webhooks/notion/database.updated",
        "payload": [
          { "name": "id", "type": "String", "selector": ["id"], "meta": { "description": "The unique identifier for the database." } },
          { "name": "title", "type": "String", "selector": ["title", 0, "plain_text"], "meta": { "description": "The title of the database." } }
        ]
      }
    ]
  },
  {
    "handle": "pages",
    "meta": {
      "short": "Pages",
      "description": "Manage Notion pages"
    },
    "endpoint": {
      "value": "v1/pages"
    },
    "fields": [
      {
        "name": "id",
        "type": "String",
        "selector": [
          "id"
        ],
        "meta": {
          "description": "Unique identifier for the page"
        }
      },
      {
        "name": "title",
        "type": "String",
        "selector": [
          "properties",
          "title",
          "title",
          0,
          "plain_text"
        ],
        "meta": {
          "description": "Title of the page"
        },
        "multivalue": true
      },
      {
        "name": "content",
        "type": "String",
        "selector": [
          "properties",
          "content",
          "rich_text",
          0,
          "plain_text"
        ],
        "meta": {
          "description": "Content of the page"
        },
        "multivalue": true
      }
    ],
    "operations": {
      "read": {
        "method": "GET",
        "path": {
          "value": "{{pageId}}"
        },
        "headers": {
          "Notion-Version": "2022-06-28",
          "Authorization": "Bearer {{apiKey}}"
        }
      },
      "create": {
        "method": "POST",
        "path": {
          "value": ""
        },
        "headers": {
          "Notion-Version": "2022-06-28",
          "Authorization": "Bearer {{apiKey}}",
          "Content-Type": "application/json"
        },
        "bodyTemplate": {
          "value": "{\"parent\": {\"type\": \"{{parentType}}\", \"{{parentType}}\": \"{{parentId}}\"},\"properties\": {\"title\": {\"title\": [{\"type\": \"text\", \"text\": {\"content\": \"{{title}}\"}}]}}}"
        }
      },
      "update": {
        "method": "PATCH",
        "path": {
          "value": "{{pageId}}"
        },
        "headers": {
          "Notion-Version": "2022-06-28",
          "Authorization": "Bearer {{apiKey}}",
          "Content-Type": "application/json"
        },
        "bodyTemplate": {
          "value": "{\"properties\": {\"title\": {\"title\": [{\"type\": \"text\", \"text\": {\"content\": \"{{title}}\"}}]}}}"
        }
      }
    },
    "webhooks": [
      {
        "event": "page.created",
        "path": "/webhooks/notion/page.created",
        "payload": [
          { "name": "id", "type": "String", "selector": ["id"], "meta": { "description": "The unique identifier for the page." } },
          { "name": "title", "type": "String", "selector": ["properties", "title", "title", 0, "plain_text"], "meta": { "description": "The title of the page." } }
        ]
      },
      {
        "event": "page.updated",
        "path": "/webhooks/notion/page.updated",
        "payload": [
          { "name": "id", "type": "String", "selector": ["id"], "meta": { "description": "The unique identifier for the page." } },
          { "name": "title", "type": "String", "selector": ["properties", "title", "title", 0, "plain_text"], "meta": { "description": "The title of the page." } }
        ]
      }
    ]
  },
  {
    "handle": "blocks",
    "meta": {
      "short": "Blocks",
      "description": "Manage Notion blocks"
    },
    "endpoint": {
      "value": "v1/blocks"
    },
    "fields": [
      {
        "name": "id",
        "type": "String",
        "selector": [
          "id"
        ],
        "meta": {
          "description": "Unique identifier for the block"
        }
      },
      {
        "name": "type",
        "type": "String",
        "selector": [
          "type"
        ],
        "meta": {
          "description": "Type of the block"
        }
      },
      {
        "name": "content",
        "type": "String",
        "selector": [
          "{{type}}",
          "rich_text",
          0,
          "plain_text"
        ],
        "meta": {
          "description": "Content of the block"
        },
        "multivalue": true
      }
    ],
    "operations": {
      "read": {
        "method": "GET",
        "path": {
          "value": "{{blockId}}"
        },
        "headers": {
          "Notion-Version": "2022-06-28",
          "Authorization": "Bearer {{apiKey}}"
        }
      },
      "list": {
        "method": "GET",
        "path": {
          "value": "{{blockId}}/children"
        },
        "headers": {
          "Notion-Version": "2022-06-28",
          "Authorization": "Bearer {{apiKey}}"
        }
      },
      "update": {
        "method": "PATCH",
        "path": {
          "value": "{{blockId}}"
        },
        "headers": {
          "Notion-Version": "2022-06-28",
          "Authorization": "Bearer {{apiKey}}",
          "Content-Type": "application/json"
        },
        "bodyTemplate": {
          "value": "{\"{{type}}\": {\"rich_text\": [{\"type\": \"text\", \"text\": {\"content\": \"{{content}}\"}}]}}"
        }
      },
      "delete": {
        "method": "DELETE",
        "path": {
          "value": "{{blockId}}"
        },
        "headers": {
          "Notion-Version": "2022-06-28",
          "Authorization": "Bearer {{apiKey}}"
        }
      }
    },
    "webhooks": [
      {
        "event": "block.updated",
        "path": "/webhooks/notion/block.updated",
        "payload": [
          { "name": "id", "type": "String", "selector": ["id"], "meta": { "description": "The unique identifier for the block." } },
          { "name": "type", "type": "String", "selector": ["type"], "meta": { "description": "The type of the block." } }
        ]
      }
    ]
  },
  {
    "handle": "search",
    "meta": {
      "short": "Search",
      "description": "Search across Notion pages and databases"
    },
    "endpoint": {
      "value": "v1/search"
    },
    "fields": [
      {
        "name": "results_0_id",
        "type": "String",
        "selector": [
          "results",
          0,
          "id"
        ],
        "meta": {
          "description": "ID of the first search result."
        },
        "multivalue": true
      },
      {
        "name": "results_0_object",
        "type": "String",
        "selector": [
          "results",
          0,
          "object"
        ],
        "meta": {
          "description": "Object type of the first result (page or database)."
        },
        "multivalue": true
      },
      {
        "name": "results_0_url",
        "type": "String",
        "selector": [
          "results",
          0,
          "url"
        ],
        "meta": {
          "description": "URL of the first search result."
        },
        "multivalue": true
      }
    ],
    "operations": {
      "list": {
        "method": "POST",
        "path": {
          "value": ""
        },
        "headers": {
          "Notion-Version": "2022-06-28",
          "Authorization": "Bearer {{apiKey}}",
          "Content-Type": "application/json"
        },
        "bodyTemplate": {
          "value": "{\"query\": \"{{query}}\", \"filter\": {\"value\": \"{{filterType}}\", \"property\": \"{{filterProperty}}\"}}"
        }
      }
    },
    "webhooks": []
  },
  {
    "handle": "users",
    "meta": {
      "short": "Users",
      "description": "Manage Notion users"
    },
    "endpoint": {
      "value": "v1/users"
    },
    "fields": [
      {
        "name": "id",
        "type": "String",
        "selector": [
          "id"
        ],
        "meta": {
          "description": "Unique identifier for the user"
        }
      },
      {
        "name": "name",
        "type": "String",
        "selector": [
          "name"
        ],
        "meta": {
          "description": "User's name"
        }
      },
      {
        "name": "type",
        "type": "String",
        "selector": [
          "type"
        ],
        "meta": {
          "description": "Type of user, e.g., 'person' or 'bot'"
        }
      },
      {
        "name": "avatar_url",
        "type": "String",
        "selector": [
          "avatar_url"
        ],
        "meta": {
          "description": "URL of the user's avatar"
        }
      },
      {
        "name": "email",
        "type": "String",
        "selector": [
          "person",
          "email"
        ],
        "meta": {
          "description": "Email address of the person"
        }
      }
    ],
    "operations": {
      "list": {
        "method": "GET",
        "path": {
          "value": ""
        },
        "headers": {
          "Notion-Version": "2022-06-28",
          "Authorization": "Bearer {{apiKey}}"
        }
      },
      "read": {
        "method": "GET",
        "path": {
          "value": "{{userId}}"
        },
        "headers": {
          "Notion-Version": "2022-06-28",
          "Authorization": "Bearer {{apiKey}}"
        }
      }
    },
    "webhooks": [
      {
        "event": "user.updated",
        "path": "/webhooks/notion/user.updated",
        "payload": [
          { "name": "id", "type": "String", "selector": ["id"], "meta": { "description": "The unique identifier for the user." } },
          { "name": "name", "type": "String", "selector": ["name"], "meta": { "description": "The name of the user." } }
        ]
      }
    ]
  },
  {
    "handle": "comments",
    "meta": {
      "short": "Comments",
      "description": "Manage Notion comments"
    },
    "endpoint": {
      "value": "v1/comments"
    },
    "fields": [
      {
        "name": "id",
        "type": "String",
        "selector": [
          "id"
        ],
        "meta": {
          "description": "Unique identifier for the comment"
        }
      },
      {
        "name": "discussion_id",
        "type": "String",
        "selector": [
          "discussion_id"
        ],
        "meta": {
          "description": "ID of the discussion the comment belongs to"
        }
      },
      {
        "name": "rich_text",
        "type": "String",
        "selector": [
          "rich_text",
          0,
          "plain_text"
        ],
        "meta": {
          "description": "Plain text content of the comment"
        },
        "multivalue": true
      },
      {
        "name": "created_time",
        "type": "String",
        "selector": [
          "created_time"
        ],
        "meta": {
          "description": "Creation time of the comment"
        }
      },
      {
        "name": "created_by_id",
        "type": "String",
        "selector": [
          "created_by",
          "id"
        ],
        "meta": {
          "description": "ID of the user who created the comment"
        }
      }
    ],
    "operations": {
      "list": {
        "method": "GET",
        "path": {
          "value": "?block_id={{blockId}}"
        },
        "headers": {
          "Notion-Version": "2022-06-28",
          "Authorization": "Bearer {{apiKey}}"
        }
      },
      "create": {
        "method": "POST",
        "path": {
          "value": ""
        },
        "headers": {
          "Notion-Version": "2022-06-28",
          "Authorization": "Bearer {{apiKey}}",
          "Content-Type": "application/json"
        },
        "bodyTemplate": {
          "value": "{\"parent\": {\"{{parentType}}\": \"{{parentId}}\"}, \"rich_text\": [{\"text\": {\"content\": \"{{content}}\"}}]}"
        }
      }
    },
    "webhooks": [
      {
        "event": "comment.created",
        "path": "/webhooks/notion/comment.created",
        "payload": [
          { "name": "id", "type": "String", "selector": ["id"], "meta": { "description": "The unique identifier for the comment." } },
          { "name": "discussion_id", "type": "String", "selector": ["discussion_id"], "meta": { "description": "The ID of the discussion the comment belongs to." } },
          { "name": "rich_text", "type": "String", "selector": ["rich_text", 0, "plain_text"], "meta": { "description": "The plain text content of the comment." } }
        ]
      }
    ]
  }
]