Integration and API Spec

Integration and API Spec

SLA Monitoring and Breach Alerting

Zendesk is polled every 15 minutes by the SLA Monitor Agent to retrieve all open tickets. The Alert Dispatch Agent writes internal notes back to individual tickets as an audit trail. Both directions use the Zendesk REST API v2.

// Poll request
GET https://{ZENDESK_SUBDOMAIN}.zendesk.com/api/v2/tickets.json?status=open&per_page=100&page={n}
Authorization: Basic {Base64(email/token:ZENDESK_API_TOKEN)}

// Ticket object fields consumed
ticket.id, ticket.created_at, ticket.updated_at, ticket.status,
ticket.assignee_id, ticket.custom_fields[ZENDESK_CLIENT_ID_FIELD_ID]

// Note write request
PUT https://{ZENDESK_SUBDOMAIN}.zendesk.com/api/v2/tickets/{ticket_id}.json
Body: { ticket: { comment: { body: '{note_text}', public: false } } }

The SLA Monitor Agent queries HubSpot to retrieve the contracted SLA tier, response window, and resolution window for each ticket's client. The Alert Dispatch Agent writes breach activity records back to the HubSpot client record when a breach occurs.

// SLA tier lookup
GET https://api.hubapi.com/crm/v3/objects/companies/{company_id}
  ?properties=sla_tier,sla_response_hours,sla_resolution_hours,hs_object_id
Authorization: Bearer {HUBSPOT_ACCESS_TOKEN}

// Breach activity record creation
POST https://api.hubapi.com/crm/v3/objects/{HUBSPOT_BREACH_OBJECT_TYPE_ID}
Authorization: Bearer {HUBSPOT_ACCESS_TOKEN}
Body: {
  properties: {
    zendesk_ticket_id: '{ticket_id}',
    sla_tier: '{sla_tier}',
    minutes_overrun: {minutes_overrun},
    breach_timestamp: '{iso8601_timestamp}'
  },
  associations: [{ to: { id: '{company_id}' }, types: [{ category: 'HUBSPOT_DEFINED', typeId: 1 }] }]
}

The Alert Dispatch Agent sends structured warning messages to the Slack channel or direct message thread of the assigned agent when a ticket crosses the 75% SLA threshold. Slack is an outbound-only integration; no events or webhooks are consumed from Slack.

// Send agent warning DM
POST https://slack.com/api/chat.postMessage
Authorization: Bearer {SLACK_BOT_TOKEN}
Body: {
  channel: '{resolved_agent_slack_user_id}',
  text: 'SLA Warning: Ticket #{ticket_id} ({client_name}) is at {pct_elapsed}% of its {sla_tier} window. {minutes_remaining} minutes remaining.',
  blocks: [ ... structured Block Kit payload ... ]
}

The Alert Dispatch Agent fires a PagerDuty incident when a ticket crosses 95% of its SLA window without a resolution or status update. PagerDuty routes the incident to the on-call support manager according to the configured escalation policy.

// Fire PagerDuty incident
POST https://events.pagerduty.com/v2/enqueue
Content-Type: application/json
Body: {
  routing_key: '{PAGERDUTY_INTEGRATION_KEY}',
  event_action: 'trigger',
  dedup_key: 'zendesk-{ticket_id}',
  payload: {
    summary: 'SLA Critical: Ticket #{ticket_id} ({client_name}) at {pct_elapsed}% of {sla_tier} window',
    severity: 'critical',
    source: 'SLA Monitor Automation',
    custom_details: {
      ticket_id: '{ticket_id}',
      sla_tier: '{sla_tier}',
      minutes_remaining: {minutes_remaining},
      assigned_agent: '{agent_email}'
    }
  }
}

The Alert Dispatch Agent sends a formatted weekly SLA summary email to the support manager every Monday morning. This is an outbound-only integration using the Gmail API via OAuth 2.0.

// Token refresh before send
POST https://oauth2.googleapis.com/token
Body: { client_id: GMAIL_CLIENT_ID, client_secret: GMAIL_CLIENT_SECRET,
        refresh_token: GMAIL_REFRESH_TOKEN, grant_type: 'refresh_token' }

// Send weekly summary
POST https://gmail.googleapis.com/gmail/v1/users/{GMAIL_SENDER_ADDRESS}/messages/send
Authorization: Bearer {access_token}
Body: { raw: '{Base64URL_encoded_MIME_message}' }

// MIME message includes:
// To: {GMAIL_SUMMARY_RECIPIENT}
// Subject: Weekly SLA Report - w/e {date}
// Content-Type: text/html
// Body: rendered HTML summary of breach_log[] accumulated since last Monday

// Credential store entries (automation platform encrypted store)
// All values injected at runtime; never appear in workflow source code

ZENDESK_SUBDOMAIN            = '{subdomain}'          // e.g. 'yourcompany'
ZENDESK_API_EMAIL            = '{agent_email}'        // API token owner email
ZENDESK_API_TOKEN            = '{api_token}'          // Zendesk Admin > API
ZENDESK_CLIENT_ID_FIELD_ID   = '{field_id}'           // Custom field numeric ID

HUBSPOT_ACCESS_TOKEN         = '{private_app_token}'  // HubSpot Private App token
HUBSPOT_SLA_TIER_PROPERTY    = 'sla_tier'             // Company property internal name
HUBSPOT_BREACH_OBJECT_TYPE_ID= '{object_type_id}'     // Custom object type ID

SLACK_BOT_TOKEN              = 'xoxb-{token}'         // Slack App Bot OAuth token
SLACK_ALERT_CHANNEL_ID       = 'C{channel_id}'        // Fallback alert channel

PAGERDUTY_INTEGRATION_KEY    = '{routing_key}'        // Events API v2 integration key
PAGERDUTY_API_KEY            = '{rest_api_key}'       // Read-only REST key (optional)

GMAIL_CLIENT_ID              = '{oauth_client_id}'
GMAIL_CLIENT_SECRET          = '{oauth_client_secret}'
GMAIL_REFRESH_TOKEN          = '{oauth_refresh_token}'
GMAIL_SENDER_ADDRESS         = '{sender@domain.com}'
GMAIL_SUMMARY_RECIPIENT      = '{manager@domain.com}'

BUSINESS_HOURS_CONFIG        = '{json_string}'        // See config schema in Dev Handover Pack
// Example structure:
// { 'gold': { tz: 'America/New_York', start: '09:00', end: '17:00', days: [1,2,3,4,5] },
//   'silver': { tz: 'America/Chicago', start: '08:00', end: '18:00', days: [1,2,3,4,5] },
//   'bronze': { tz: 'America/Los_Angeles', start: '09:00', end: '17:00', days: [1,2,3,4,5] } }