Audience: BSAs/BSEs and engineers integrating, operating, or extending the system.

Boundary: Dev Zendesk + local n8n + carrier sandbox only. No production access.

Business purpose

This document specifies the interfaces between the four integrated systems — Zendesk, n8n, FedEx, and UPS — including direction, authentication, payloads, and resilience rules, so an analyst or engineer can reason about the data handoffs without reading the workflow internals.

Scope

In scope: the Zendesk↔n8n webhook + REST interfaces, the n8n Public API deploy interface, and the FedEx/UPS OAuth + Track interfaces, with their auth methods and resilience contracts.

Out of scope: carrier push notifications, production endpoints, and any non-FedEx/UPS carrier.

Integration landscape

flowchart TB
  subgraph dev["Dev and sandbox only (no production access)"]
    direction LR
    ZD["Zendesk REST API<br/>Custom Objects v2, triggers, webhooks, jobs<br/>auth: Basic email/token + HMAC webhook"]
    N8N["Local n8n<br/>Public API deploy<br/>auth: X-N8N-API-KEY"]
    FEDEX["FedEx Track + OAuth<br/>apis-sandbox.fedex.com<br/>auth: form creds then Bearer"]
    UPS["UPS Track + OAuth<br/>wwwcie.ups.com (CIE)<br/>auth: Basic then Bearer"]
  end
  N8N -->|"ingest, sync, prune writes"| ZD
  ZD -->|"trigger webhook (HMAC)"| N8N
  N8N -->|"OAuth + Track batched"| FEDEX
  N8N -->|"OAuth + Track per number"| UPS

Interfaces

1. Zendesk → n8n (inbound webhook, ingestion)

• Direction: Zendesk ticket trigger → n8n Ingest webhook (via cloudflared tunnel).
• Trigger condition: tracking-number ticket field transitions to present.
• Transport: POST JSON, custom body (ticket_id, tracking_number, carrier, requester_email).
• Auth / integrity: X-Zendesk-Webhook-Signature = base64 HMAC-SHA256 over timestamp + raw body; the receiver verifies the signature and timestamp freshness (replay window) and rejects with 401.
• Responses: 200 (created/linked, idempotent), 401 (bad signature), 422 (missing/invalid tracking or undeterminable carrier).
• Idempotency: upsert by external_id; duplicate deliveries do not double-create.

2. n8n → Zendesk (REST, reads + writes)

• Direction: n8n → Zendesk REST API.
• Auth: Basic email/token ({email}/token:{api_token}).