| name | notion-incident-runbook |
| description | Execute Notion incident response procedures with triage, mitigation, and postmortem.
Use when responding to Notion API outages, investigating errors, or running
post-incident reviews for Notion integration failures. Trigger with phrases like
"notion incident", "notion outage", "notion down", "notion on-call",
"notion emergency", "notion broken".
|
| allowed-tools | Read, Bash(kubectl:*), Bash(curl:*) |
| version | 1.38.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","productivity","notion"] |
| compatibility | Designed for Claude Code |
Notion Incident Runbook
Overview
Rapid incident response for Notion API failures. This runbook drives a sub-5-minute
triage that classifies the failure as Notion-side vs. integration-side, then routes to
per-error-type mitigation, cached fallback, and a structured postmortem.
Deep material — full triage scripts, remediation code, and templates — lives in
references/; this file is the high-level flow you follow live.
Prerequisites
- Access to application monitoring dashboards and log aggregator
NOTION_TOKEN environment variable set for diagnostic API callscurl and jq installed for quick CLI triage- Python alternative:
notion-client (pip install notion-client)
- Communication channels configured (Slack webhook, PagerDuty, etc.)
Instructions
Step 1: Quick Triage (Under 5 Minutes)
At first alert, decide whether the fault is Notion's or yours. Check the platform
status page, then test your own auth. This one call is enough to start:
curl -sf -o /dev/null -w "%{http_code}" \
https://api.notion.com/v1/users/me \
-H "Authorization: Bearer ${NOTION_TOKEN}" \
-H "Notion-Version: 2022-06-28"
Map the result: 200 → integration-side, 401 → token expired/revoked, 429 →
rate limited, 000 → network/DNS. If status.notion.so shows an active incident, it
is Notion-side regardless of your auth code.
Read references/triage.md for the full notion-triage.sh
diagnostic (status page + auth + DB-query latency + auto-classification) and a
TypeScript triageNotionHealth() equivalent for in-app health checks.
Step 2: Decision Tree and Mitigation
Route the classification to a remediation path:
- Notion-side outage — enable cached/fallback mode, notify users, monitor the
status page. Do NOT restart or rotate tokens.
- 401 token expired/revoked — regenerate at
notion.so/my-integrations, update the
secret manager, restart the app.
- 429 rate limited — you are exceeding the 3 req/s average; find runaway loops or
webhook storms, drop concurrency to 1, add exponential backoff.
