How to Automate Notion Team Collaboration using the API

Understanding the Notion API

Setting Up Notion API Authentication

Notion uses Bearer tokens for internal integrations. For collaboration automation you need Insert comments (to post threaded notifications) and Read user information capabilities in addition to Read content. Without Insert comments, POST /v1/comments returns 403 restricted_resource. Webhook signatures use HMAC-SHA256 keyed by the verification_token from the webhook subscription.

1. 1Go to notion.so/my-integrations (workspace owner required)
2. 2Create or open your integration and enable: Read content, Insert comments, Read user information
3. 3Copy the Internal Integration Secret (ntn_ prefix)
4. 4Share the target database with the integration via '...' > Connections
5. 5Set up a public HTTPS endpoint for webhook delivery (use ngrok for local testing)
6. 6Store credentials: export NOTION_TOKEN=ntn_your_token
7. 7After creating the webhook subscription (next section), store the verification_token for signature verification

1import os
2import hmac
3import hashlib
4
5NOTION_TOKEN = os.environ['NOTION_TOKEN']
6WEBHOOK_SECRET = os.environ.get('NOTION_WEBHOOK_SECRET', '')
7
8HEADERS = {
9    'Authorization': f'Bearer {NOTION_TOKEN}',
10    'Notion-Version': '2025-09-03',
11    'Content-Type': 'application/json'
12}
13
14def verify_notion_webhook(raw_body: bytes, signature_header: str) -> bool:
15    """Verify X-Notion-Signature header using HMAC-SHA256."""
16    expected = hmac.new(
17        WEBHOOK_SECRET.encode(),
18        raw_body,
19        hashlib.sha256
20    ).hexdigest()
21    return hmac.compare_digest(f'sha256={expected}', signature_header)

Key endpoints

1{"url":"https://yourapp.com/webhooks/notion","events":["page.updated"],"resource":{"type":"database","id":"DATABASE_ID"}}

1{"id":"webhook-id","url":"https://yourapp.com/webhooks/notion","events":["page.updated"],"verification_token":"abc123","active":false}

1{"object":"page","id":"page-id","properties":{"Name":{"title":[{"plain_text":"Fix auth bug"}]},"Assignee":{"people":[{"id":"user-id","name":"Alice","object":"user"}]},"Status":{"status":{"name":"In Progress"}}}}

1{"parent":{"page_id":"PAGE_ID"},"rich_text":[{"type":"text","text":{"content":"Assigned to "}},{"type":"mention","mention":{"type":"user","user":{"id":"USER_ID"}}}]}

1{"object":"comment","id":"comment-id","parent":{"type":"page_id","page_id":"page-id"},"rich_text":[{"type":"text","text":{"content":"Assigned to "}},{"type":"mention","mention":{"user":{"id":"user-id","name":"Alice"}}}]}

1{"object":"user","id":"user-id","type":"person","name":"Alice Smith","person":{"email":"alice@example.com"}}

Step-by-step automation

1curl -X POST 'https://api.notion.com/v1/webhooks' \
2  -H 'Authorization: Bearer $NOTION_TOKEN' \
3  -H 'Notion-Version: 2026-03-01' \
4  -H 'Content-Type: application/json' \
5  -d '{
6    "url": "https://yourapp.com/webhooks/notion",
7    "events": ["page.updated"],
8    "resource": {"type": "database", "id": "YOUR_DATABASE_ID"}
9  }'

1# Webhook handler example — verify signature and fetch page
2curl -X GET 'https://api.notion.com/v1/pages/PAGE_ID_FROM_WEBHOOK' \
3  -H 'Authorization: Bearer $NOTION_TOKEN' \
4  -H 'Notion-Version: 2025-09-03'

1curl -X POST 'https://api.notion.com/v1/comments' \
2  -H 'Authorization: Bearer $NOTION_TOKEN' \
3  -H 'Notion-Version: 2025-09-03' \
4  -H 'Content-Type: application/json' \
5  -d '{
6    "parent": {"page_id": "PAGE_ID"},
7    "rich_text": [
8      {"type": "text", "text": {"content": "This task has been assigned to "}},
9      {"type": "mention", "mention": {"type": "user", "user": {"id": "USER_ID"}}},
10      {"type": "text", "text": {"content": ". Please review and update the status."}}
11    ]
12  }'

1# First fetch user details
2curl -X GET 'https://api.notion.com/v1/users/USER_ID' \
3  -H 'Authorization: Bearer $NOTION_TOKEN' \
4  -H 'Notion-Version: 2025-09-03'
5
6# Then send Slack notification
7curl -X POST 'https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK' \
8  -H 'Content-Type: application/json' \
9  -d '{"text": ":pencil: Alice Smith has been assigned: Fix auth bug"}'

Complete working code

This complete Flask webhook handler processes Notion page.updated events: it verifies the X-Notion-Signature, fetches the updated page, checks for Assignee property changes, posts a threaded comment on the page mentioning the assignee, and sends a Slack notification. Returns 200 immediately and processes asynchronously.

1import os
2import hmac
3import hashlib
4import threading
5import requests
6from flask import Flask, request, jsonify
7
8app = Flask(__name__)
9
10NOTION_TOKEN = os.environ['NOTION_TOKEN']
11WEBHOOK_SECRET = os.environ['NOTION_WEBHOOK_SECRET']
12SLACK_WEBHOOK = os.environ.get('SLACK_WEBHOOK_URL')
13
14NOTION_HEADERS = {
15    'Authorization': f'Bearer {NOTION_TOKEN}',
16    'Notion-Version': '2025-09-03',
17    'Content-Type': 'application/json'
18}
19
20def verify_sig(raw: bytes, sig: str) -> bool:
21    d = hmac.new(WEBHOOK_SECRET.encode(), raw, hashlib.sha256).hexdigest()
22    return hmac.compare_digest(f'sha256={d}', sig)
23
24def fetch_page(page_id):
25    r = requests.get(f'https://api.notion.com/v1/pages/{page_id}', headers=NOTION_HEADERS)
26    return r.json() if r.ok else None
27
28def post_comment(page_id, user_id, task_name):
29    requests.post('https://api.notion.com/v1/comments', headers=NOTION_HEADERS, json={
30        'parent': {'page_id': page_id},
31        'rich_text': [
32            {'type': 'text', 'text': {'content': f'Assigned to '}},
33            {'type': 'mention', 'mention': {'type': 'user', 'user': {'id': user_id}}},
34            {'type': 'text', 'text': {'content': f' — {task_name}. Please update status when you start.'}}
35        ]
36    })
37
38def notify_slack(user_name, task_name, page_id):
39    if not SLACK_WEBHOOK:
40        return
41    url = f"https://notion.so/{page_id.replace('-','')}"
42    requests.post(SLACK_WEBHOOK, json={
43        'text': f':pencil: *{user_name}* assigned: {task_name} <{url}|Open>'
44    })
45
46def process_event(payload):
47    page_id = payload.get('entity', {}).get('id')
48    if not page_id:
49        return
50    page = fetch_page(page_id)
51    if not page:
52        return
53    title = page['properties'].get('Name', {}).get('title', [])
54    task_name = title[0]['plain_text'] if title else 'Untitled'
55    assignees = page['properties'].get('Assignee', {}).get('people', [])
56    for a in assignees:
57        try:
58            post_comment(page_id, a['id'], task_name)
59            notify_slack(a.get('name', 'Team member'), task_name, page_id)
60        except Exception as e:
61            print(f'Error processing assignee {a["id"]}: {e}')
62
63@app.route('/webhooks/notion', methods=['POST'])
64def webhook():
65    sig = request.headers.get('X-Notion-Signature', '')
66    raw = request.get_data()
67    if not verify_sig(raw, sig):
68        return jsonify({'error': 'bad signature'}), 401
69    payload = request.json
70    threading.Thread(target=process_event, args=(payload,), daemon=True).start()
71    return jsonify({'ok': True})
72
73if __name__ == '__main__':
74    app.run(port=3000)

Error handling

Rate Limits for Notion API

1import time
2import requests
3
4def notion_call(method, url, headers, **kwargs):
5    for attempt in range(5):
6        resp = getattr(requests, method)(url, headers=headers, **kwargs)
7        if resp.status_code == 429:
8            wait = int(resp.headers.get('Retry-After', 2 ** attempt))
9            time.sleep(wait)
10            continue
11        return resp
12    raise Exception('Max retries exceeded')

• Return HTTP 200 from the webhook handler immediately and process the event asynchronously in a background thread or queue
• Add 350ms delays between the follow-up API calls within each event handler to stay under 3 req/s
• During bulk operations (e.g., 20 tasks reassigned simultaneously), 20 webhook events each triggering 3 API calls = 60 requests in seconds — use a queue to serialize processing
• Cache user details (GET /v1/users/{id}) for short periods — user names and emails change rarely
• Monitor your webhook delivery logs for 429 responses from Notion — sustained throttling may indicate you need to reduce event subscriptions

Security checklist

Automation use cases

No-code alternatives

Don't want to write code? These platforms can automate the same workflows visually.

Best practices

• Pin Notion-Version: 2026-03-01 specifically for webhook management endpoints — the webhook subscription API requires this version
• Process webhook events asynchronously — always return 200 from the handler within 200ms
• Verify X-Notion-Signature on every incoming webhook using HMAC-SHA256 with your verification_token
• Cache user details to reduce follow-up API calls per event — user data changes infrequently
• Use a job queue (Redis + Bull, SQS) for high-volume workspaces where many events can fire simultaneously
• Test webhook handlers locally with ngrok before deploying to production — Notion requires a public HTTPS URL
• Log all webhook events with their entity IDs and timestamps for debugging and audit purposes

Ask AI to help

Copy one of these prompts to get a personalized, working implementation.

Related automations