Integration and API Spec

Integration and API Spec

Audit Preparation Workflow

Acts as the system of record for audit records and evidence checklists. The automation reads audit records to trigger the Evidence Collection Agent and writes checklist item status updates throughout the cycle. The DocuSign completion webhook also writes back to Notion.

// Trigger poll — Audits database
POST /v1/databases/{NOTION_AUDIT_DB_ID}/query
  filter: { property: 'Status', select: { equals: 'Confirmed' } }
// Status update write — Checklist item
PATCH /v1/pages/{page_id}
  properties: { Status: { select: { name: 'Verified' } }, Drive_File_URL: { url: '...' } }
// DocuSign webhook write-back
PATCH /v1/pages/{checklist_page_id}
  properties: { Status: { select: { name: 'Verified' } }, DocuSign_Envelope_ID: { rich_text: [...] } }

Stores all uploaded evidence documents and hosts the structured folder hierarchy per audit cycle. Agent 1 creates the folder structure on audit trigger. Agent 2 monitors the submission folder for new uploads and validates file metadata against the Notion checklist.

// Create submission folder
POST https://www.googleapis.com/drive/v3/files
  { name: '{AuditType}_{YYYY}_{CycleRef}', mimeType: 'application/vnd.google-apps.folder',
    parents: [DRIVE_AUDIT_ROOT_FOLDER_ID] }
// Register watch channel on submission folder
POST https://www.googleapis.com/drive/v3/files/{folderId}/watch
  { id: '{uuid}', type: 'web_hook', address: DRIVE_WEBHOOK_RECEIVER_URL, expiration: now+86400000 }
// List new files (polling fallback)
GET https://www.googleapis.com/drive/v3/files
  ?q='{FOLDER_ID}'+in+parents+and+trashed=false+and+modifiedTime>'{last_poll}'
  &fields=files(id,name,mimeType,modifiedTime,parents,size)

Sends personalised stakeholder assignment emails and overdue reminder emails on behalf of the compliance manager. All emails are sent via the Gmail API using the compliance manager's authenticated account so replies land in their inbox.

// Send assignment email
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
  { raw: base64url(RFC2822 message) }
// Message headers
  To: {stakeholder_email}
  From: GMAIL_SENDER_ADDRESS
  Subject: 'Action required: Audit evidence request [{audit_ref}]'
  Body: GMAIL_ASSIGNMENT_TEMPLATE rendered with stakeholder context
// Overdue reminder — same endpoint, GMAIL_REMINDER_TEMPLATE

Posts overdue alerts and cycle completion notifications to internal Slack channels. The bot posts to a compliance-specific channel for overdue items and a leadership channel for completion. No Slack messages are sent to external parties.

// Post overdue alert
POST https://slack.com/api/chat.postMessage
  Authorization: Bearer SLACK_BOT_TOKEN
  { channel: SLACK_COMPLIANCE_CHANNEL_ID,
    blocks: [ rendered SLACK_OVERDUE_TEMPLATE with stakeholder context ] }
// Post completion alert
POST https://slack.com/api/chat.postMessage
  { channel: SLACK_LEADERSHIP_CHANNEL_ID,
    blocks: [ rendered SLACK_COMPLETION_TEMPLATE with audit_ref and pack link ] }
// Email to Slack ID lookup
GET https://slack.com/api/users.lookupByEmail?email={stakeholder_email}
  -> user.id used as {{stakeholder_slack_id}} in template

Routes declaration documents to nominated signatories when the Document Review Agent identifies that a checklist item has the Signature_Required flag set. DocuSign returns a completion webhook that the orchestration layer uses to update the Notion checklist item status to Verified.

// Create and send envelope from template
POST {DOCUSIGN_BASE_URL}/v2.1/accounts/{DOCUSIGN_ACCOUNT_ID}/envelopes
  Authorization: Bearer {access_token}
  { status: 'sent',
    templateId: DOCUSIGN_TEMPLATE_MAP[document_type],
    templateRoles: [{ roleName: 'Signatory', name: recipient_name, email: recipient_email }] }
// Inbound Connect webhook payload (envelope-completed)
  POST DOCUSIGN_CONNECT_RECEIVER_URL
  Headers: X-DocuSign-Signature-1: {hmac_signature}
  Body: { envelopeId, status: 'completed', completedDateTime, envelopeSummary: {...} }
// Validate HMAC before processing
  HMAC-SHA256(request_body, DOCUSIGN_CONNECT_HMAC_KEY) == X-DocuSign-Signature-1

// Notion
NOTION_API_TOKEN            = <internal integration token from notion.so/my-integrations>
NOTION_AUDIT_DB_ID          = <Notion database ID for Audits database>
NOTION_CHECKLIST_DB_ID      = <Notion database ID for Evidence Checklist database>

// Google (Drive + Gmail)
GOOGLE_SA_KEY_JSON          = <service account JSON key file contents, base64-encoded>
GOOGLE_IMPERSONATION_EMAIL  = <compliance manager Google Workspace email address>
GMAIL_CLIENT_ID             = <OAuth 2.0 client ID from Google Cloud Console>
GMAIL_CLIENT_SECRET         = <OAuth 2.0 client secret>
GMAIL_REFRESH_TOKEN         = <long-lived refresh token from compliance manager OAuth flow>
GMAIL_SENDER_ADDRESS        = <compliance manager Gmail address>
DRIVE_AUDIT_ROOT_FOLDER_ID  = <Google Drive folder ID of the top-level audit evidence folder>
DRIVE_WEBHOOK_RECEIVER_URL  = <public HTTPS URL of the orchestration layer webhook endpoint>

// Slack
SLACK_BOT_TOKEN             = <xoxb- bot token from Slack app settings>
SLACK_COMPLIANCE_CHANNEL_ID = <channel ID of the internal compliance Slack channel>
SLACK_LEADERSHIP_CHANNEL_ID = <channel ID of the leadership notification channel>

// DocuSign
DOCUSIGN_INTEGRATION_KEY        = <DocuSign app integration key (client ID)>
DOCUSIGN_RSA_PRIVATE_KEY        = <RSA private key PEM for JWT grant, newlines escaped>
DOCUSIGN_IMPERSONATION_GUID     = <DocuSign user GUID of the compliance manager account>
DOCUSIGN_ACCOUNT_ID             = <DocuSign account ID>
DOCUSIGN_BASE_URL               = <DocuSign REST API base URL e.g. https://na4.docusign.net/restapi>
DOCUSIGN_CONNECT_RECEIVER_URL   = <public HTTPS URL of the DocuSign Connect webhook endpoint>
DOCUSIGN_CONNECT_HMAC_KEY       = <HMAC secret configured in DocuSign Connect settings>
DOCUSIGN_TEMPLATE_MAP           = <JSON object mapping document type keys to template IDs>

// Gmail templates
GMAIL_ASSIGNMENT_TEMPLATE   = <parameterised RFC2822 body string with placeholders>
GMAIL_REMINDER_TEMPLATE     = <parameterised RFC2822 body string with placeholders>

// Slack templates
SLACK_OVERDUE_TEMPLATE      = <Block Kit JSON string with placeholders>
SLACK_COMPLETION_TEMPLATE   = <Block Kit JSON string with placeholders>