Integration and API Spec

Integration and API Spec

Incident and Issue Reporting

Provides the structured incident intake trigger. The connected Google Sheet acts as the live response destination. The orchestration layer polls or watches the sheet for new rows rather than connecting to Forms directly via webhook.

// Output from Forms (row in connected Sheet)
form_response.timestamp         // ISO 8601 string
form_response.reporter_email    // string, validated email
form_response.description       // string, free text
form_response.location          // string
form_response.category_estimate // string, one of predefined options
form_response.severity_estimate // string, one of: Low | Medium | High | Critical
form_response.attachment_url    // string, Google Drive URL or empty string

Serves dual roles: acts as the Forms response destination that triggers the Incident Triage Agent, and as the central incident log written to and updated throughout the lifecycle of each incident.

// Write on new incident (Incident Log tab)
log_row.incident_id           // string, format INC-YYYYMMDD-NNN
log_row.timestamp             // ISO 8601
log_row.reporter_email        // string
log_row.description           // string
log_row.location              // string
log_row.category              // string, output of triage classification
log_row.severity_score        // integer 1-4 (1=Low, 2=Medium, 3=High, 4=Critical)
log_row.assigned_owner        // string, Slack user ID or email
log_row.deadline              // ISO 8601 date
log_row.status                // string: Open | In Progress | Resolved | Closed
log_row.notion_url            // string, full Notion page URL
log_row.resolution_notes      // string, empty on creation
log_row.close_timestamp       // string, empty on creation

// Update on resolution
log_row.status                // string: Resolved
log_row.resolution_notes      // string
log_row.close_timestamp       // ISO 8601

Receives a structured page creation call from the Incident Triage Agent for every new incident. Pages use a fixed database template with defined properties matching the incident schema. Investigation notes and resolution details are appended by owners directly in Notion.

// Input to Notion API (page create)
notion_page.parent.database_id  // NOTION_DATABASE_ID from credential store
notion_page.properties.Incident_ID       // title block
notion_page.properties.Reporter_Email    // email type
notion_page.properties.Description       // rich_text
notion_page.properties.Location          // select
notion_page.properties.Category          // select
notion_page.properties.Severity_Score    // number
notion_page.properties.Severity_Label    // select
notion_page.properties.Assigned_Owner    // rich_text (Slack ID or name)
notion_page.properties.Deadline          // date
notion_page.properties.Status            // select: Open
notion_page.properties.Attachment_URL    // url
notion_page.properties.Sheets_Row_Ref    // number
notion_page.properties.Sheets_Synced     // checkbox: false

// Output from Notion (on resolution poll)
notion_page.id                           // string, Notion page ID
notion_page.url                          // string, public page URL
notion_page.properties.Status            // select: Resolved
notion_page.properties.Sheets_Synced     // checkbox: false (filter condition)
notion_page.properties.Resolution_Notes  // rich_text

Used by the Notification and Escalation Agent to send owner assignment messages and scheduled status-chase reminders. Messages are sent via the Slack Web API using a bot token. The bot must be invited to the relevant channels or must use direct message (IM) opening.

// chat.postMessage payload (owner assignment)
slack_message.channel          // string, Slack user ID (UXXXXXXXX) for DM
slack_message.text             // string, plain text fallback
slack_message.blocks[]         // Block Kit: section with incident summary,
                               //   severity label, deadline, Notion URL button

// chat.postMessage payload (status-chase reminder)
slack_message.channel          // string, same Slack user ID
slack_message.text             // string: 'Reminder: INC-YYYYMMDD-NNN is due [date]'
slack_message.blocks[]         // Block Kit: reminder section with Notion link

Sends automated acknowledgement emails to the incident reporter confirming receipt, the assigned incident ID, the owner name, and the expected resolution timeframe. Uses the Gmail API send method via the authorised Google account.

// gmail.users.messages.send payload
gmail_message.to               // string, form_response.reporter_email
gmail_message.from             // string, GMAIL_SENDER_ADDRESS
gmail_message.subject          // string, rendered from template
gmail_message.body_html        // string, rendered HTML from template
gmail_message.body_text        // string, rendered plain text from template
gmail_message.references       // empty for first send

Receives escalation events from the Notification and Escalation Agent when an incident is classified as High (severity score 3) or Critical (severity score 4). Uses the PagerDuty Events API v2 to create an alert on the configured service.

// Events API v2 POST body
pd_event.routing_key           // string, PAGERDUTY_ROUTING_KEY
pd_event.event_action          // string: 'trigger'
pd_event.dedup_key             // string, incident_id (e.g. INC-20240617-001)
pd_event.payload.summary       // string: 'INC-20240617-001 [Critical]: {{description_truncated}}'
pd_event.payload.severity      // string: 'critical' or 'error' (mapped from score)
pd_event.payload.source        // string: 'Incident and Issue Reporting Automation'
pd_event.payload.timestamp     // ISO 8601
pd_event.payload.custom_details.incident_id    // string
pd_event.payload.custom_details.category       // string
pd_event.payload.custom_details.location       // string
pd_event.payload.custom_details.reporter_email // string
pd_event.payload.custom_details.notion_url     // string
pd_event.links[].href          // string, Notion page URL
pd_event.links[].text          // string: 'View Notion Record'

// Google (shared across Forms, Sheets, Gmail)
GOOGLE_OAUTH_CLIENT_ID          // string, from Google Cloud Console
GOOGLE_OAUTH_CLIENT_SECRET      // string, from Google Cloud Console
GOOGLE_OAUTH_REFRESH_TOKEN      // string, obtained during OAuth flow
GMAIL_SENDER_ADDRESS            // string, e.g. incidents@[YourCompany.com]

// Google Sheets
SHEETS_SPREADSHEET_ID           // string, from Sheet URL
SHEETS_RESPONSES_TAB_NAME       // string, default: 'Form Responses 1'
SHEETS_LOG_TAB_NAME             // string, default: 'Incident Log'
SHEETS_LAST_ROW_INDEX           // integer, updated by workflow on each poll run
SHEETS_NOTIFIED_COL_NAME        // string, default: 'Notified'

// Notion
NOTION_API_TOKEN                // string, internal integration token
NOTION_DATABASE_ID              // string, from Notion database URL

// Slack
SLACK_BOT_TOKEN                 // string, xoxb- prefixed bot token
SLACK_INCIDENT_CHANNEL_ID       // string, fallback channel ID

// PagerDuty
PAGERDUTY_ROUTING_KEY           // string, Events API v2 integration key
PAGERDUTY_API_KEY               // string, REST API key (setup/admin use only)
PAGERDUTY_TRIGGER_THRESHOLD     // integer, default: 3
PAGERDUTY_SERVICE_NAME          // string, human-readable label for logs

// Triage configuration
SEVERITY_RUBRIC_VERSION         // string, e.g. 'v1.2' (for audit reference)
OWNER_ROUTING_TABLE             // JSON object: { category: { slack_id, email, name } }
REMINDER_SCHEDULE_HOURS         // JSON array: [-24, 0, 24] (relative to deadline)

// Email template
GMAIL_SUBJECT_TEMPLATE          // string with {{incident_id}} placeholder
GMAIL_BODY_HTML_TEMPLATE        // string with all required placeholders
GMAIL_BODY_TEXT_TEMPLATE        // string, plain text version