Integration and API Spec

Integration and API Spec

GDPR / Data Privacy Request Handling

Typeform acts as the sole authoritative intake channel. A new form submission fires an inbound webhook to the orchestration layer, which parses the payload and passes it to Agent 1. The form must be configured with required fields matching the Notion case record schema.

// Inbound webhook payload (key fields)
event_id: string          // Typeform event UUID
form_response.submitted_at: ISO8601 timestamp
form_response.answers[].field.ref: string   // matches TYPEFORM_FIELD_REF_*
form_response.answers[].text: string        // requester_name, request_type, request_detail
form_response.answers[].email: string       // requester_email
// Signature header
Typeform-Signature: sha256=<hmac_hex>

Notion is used by both agents. Agent 1 creates the initial case record and writes the verification email status. Agent 2 writes the compiled draft response and updates the record when the reviewer approves. The orchestration layer polls the identity_verified field to gate Agent 2's trigger.

// Agent 1 creates case record (POST /v1/pages)
parent.database_id: NOTION_CASES_DB_ID
properties.requester_name.title[].text.content: string
properties.requester_email.email: string
properties.request_type.select.name: 'SAR' | 'Erasure' | 'Rectification'
properties.Status.select.name: 'Pending Verification'
properties.deadline_date.date.start: ISO8601 (submission_date + 30 days)
properties.identity_verified.checkbox: false
properties.agent2_triggered.checkbox: false
// Agent 2 updates case record (PATCH /v1/pages/{page_id})
properties.Status.select.name: 'Awaiting Review'
properties.draft_page_id.relation[].id: draft_page_id
properties.hubspot_contact_id.rich_text[].text.content: string
// Closer update after approval
properties.Status.select.name: 'Closed'
properties.completion_date.date.start: ISO8601
properties.outcome.select.name: 'Approved'
properties.reviewer_name.rich_text[].text.content: string

Gmail is used by Agent 1 to send the identity verification email immediately after the Notion case record is created. It is used again at the end of the workflow to send the approved final response and data pack to the requester. Both sends use message templates with dynamic placeholder substitution.

// Gmail send (POST /gmail/v1/users/me/messages/send)
// Verification email (Agent 1)
to: requester_email (from Typeform payload)
subject: 'Your privacy request has been received - identity verification required'
body: render(GMAIL_VERIFICATION_TEMPLATE_ID, {
  requester_name, request_type, deadline_date, case_id, notion_case_url
})
// Final response email (Agent 2, post-approval)
to: requester_email (from Notion case record)
subject: 'Your {{request_type}} request - response from [YourCompany.com]'
body: render(GMAIL_RESPONSE_TEMPLATE_ID, {
  requester_name, request_type, completion_date, reviewer_name, data_summary_url
})
attachments: [data_pack.pdf] if request_type == 'SAR'

HubSpot is the primary source of personal data held on the requester. Agent 2 queries HubSpot via the CRM API once identity is confirmed in Notion, retrieving contact records, associated deals, notes, and email history. All retrieved data is structured and written to the Notion draft response page.

// Contact search (POST /crm/v3/objects/contacts/search)
filterGroups[0].filters[0].propertyName: 'email'
filterGroups[0].filters[0].operator: 'EQ'
filterGroups[0].filters[0].value: requester_email
properties: ['firstname','lastname','email','phone','createdate','hs_lead_status']
// Association fetch (GET /crm/v4/objects/contacts/{contact_id}/associations/{object_type})
// Returns: deal IDs, note IDs, email IDs
// Deal detail (GET /crm/v3/objects/deals/{deal_id})
properties: ['dealname','amount','dealstage','createdate','closedate']
// Notes (GET /crm/v3/objects/notes/{note_id})
properties: ['hs_note_body','hs_timestamp','hubspot_owner_id']
// Output written to Notion draft page
contact_summary: { id, name, email, phone, created, lead_status }
deals: [{ id, name, amount, stage, created, closed }]
notes: [{ id, body, timestamp, owner_id }]
email_count: integer

Slack delivers the reviewer notification at the end of Agent 2's run, providing a direct link to the Notion draft and an explicit approval prompt. The message is sent to a designated private channel or direct message to the assigned reviewer. No inbound Slack interaction is used in the current build; approval is recorded in Notion directly.

// Outbound message (POST https://slack.com/api/chat.postMessage)
channel: SLACK_REVIEWER_CHANNEL_ID
blocks: [
  { type: 'header', text: 'Privacy Request Ready for Review' },
  { type: 'section', fields: [
    { type: 'mrkdwn', text: '*Case ID:* {{case_id}}' },
    { type: 'mrkdwn', text: '*Requester:* {{requester_name}}' },
    { type: 'mrkdwn', text: '*Type:* {{request_type}}' },
    { type: 'mrkdwn', text: '*Deadline:* {{deadline_date}}' }
  ]},
  { type: 'section', text: { type: 'mrkdwn',
    text: '<{{notion_draft_url}}|Open draft in Notion>' }},
  { type: 'section', text: { type: 'mrkdwn',
    text: 'Mark the case Approved or Rejected in Notion before responding.' }}
]
// Expected API response
{ ok: true, channel: string, ts: string }

// ---- Typeform ----
TYPEFORM_WEBHOOK_SECRET        = '<hmac_secret_from_typeform_webhook_settings>'
TYPEFORM_FORM_ID               = '<form_id_from_typeform_dashboard>'
TYPEFORM_FIELD_REF_NAME        = '<ref_string_for_requester_name_field>'
TYPEFORM_FIELD_REF_EMAIL       = '<ref_string_for_requester_email_field>'
TYPEFORM_FIELD_REF_TYPE        = '<ref_string_for_request_type_field>'
TYPEFORM_FIELD_REF_DETAIL      = '<ref_string_for_request_detail_field>'

// ---- Notion ----
NOTION_API_TOKEN               = '<internal_integration_token>'
NOTION_CASES_DB_ID             = '<database_id_for_case_records>'
NOTION_DRAFT_DB_ID             = '<database_id_for_draft_response_pages>'

// ---- Gmail ----
GMAIL_CLIENT_ID                = '<google_oauth_client_id>'
GMAIL_CLIENT_SECRET            = '<google_oauth_client_secret>'
GMAIL_OAUTH_REFRESH_TOKEN      = '<authorised_user_refresh_token>'
GMAIL_SENDER_ADDRESS           = 'privacy@[yourdomain]'
GMAIL_VERIFICATION_TEMPLATE_ID = '<template_identifier_in_template_store>'
GMAIL_RESPONSE_TEMPLATE_ID     = '<template_identifier_in_template_store>'

// ---- HubSpot ----
HUBSPOT_PRIVATE_APP_TOKEN      = '<private_app_token_from_hubspot_settings>'
HUBSPOT_PORTAL_ID              = '<hubspot_portal_id>'
HUBSPOT_DEAL_TYPE_ID           = '<object_type_id_for_deals>'
HUBSPOT_NOTE_TYPE_ID           = '<object_type_id_for_notes>'
HUBSPOT_EMAIL_TYPE_ID          = '<object_type_id_for_email_engagements>'

// ---- Slack ----
SLACK_BOT_TOKEN                = '<bot_oauth_token_xoxb-...>'
SLACK_REVIEWER_CHANNEL_ID      = '<channel_id_not_channel_name>'
SLACK_REVIEWER_USER_ID         = '<slack_user_id_for_dm_fallback>'

// ---- Orchestration ----
ENV                            = 'sandbox' | 'production'
POLL_INTERVAL_SECONDS          = '300'