Protocol Raw System Architecture
Layer 3: Integration Specifications
Version: 1.0
Status: Production Reference
Last Updated: January 2026
Owner: Protocol Raw Operations
1. Integration Overview
Protocol Raw integrates with 12 external systems. This document provides complete API specifications for each.
| System |
Type |
Direction |
Primary Use |
| Shopify |
E-commerce |
Bidirectional |
Orders, customers |
| Seal Subscriptions |
Subscription mgmt |
Bidirectional |
Subscription state |
| DPD Courier |
Delivery |
Inbound |
Tracking events |
| Customer.io |
Email platform |
Outbound |
All customer emails |
| Gmail |
Email inbox |
Inbound |
Support, lab results |
| OpenAI |
AI |
Outbound |
Lab parsing, embeddings |
| Anthropic Claude |
AI |
Outbound |
Support classification |
| Slack |
Alerting |
Outbound |
Operational alerts |
| Browserless |
PDF generation |
Outbound |
Labels, reports |
| Resend |
Email |
Outbound |
Partner notifications |
| OpenWeatherMap |
Weather |
Outbound |
PCM calculation |
| Metabase |
Analytics |
Inbound |
Dashboards |
2. Shopify
2.1 Inbound: orders/create Webhook
| Attribute |
Value |
| Endpoint |
https://znfjpllsiuyezqlneqzr.supabase.co/functions/v1/shopify-webhook-handler |
| Auth |
HMAC-SHA256 (X-Shopify-Hmac-Sha256 header) |
| SOP |
SOP-00 |
Key Payload Fields:
- id → orders.shopify_order_id
- name → orders.shopify_order_number
- customer → customers table (upsert)
- line_items → order_items table
- shipping_address → delivery address
2.2 Outbound: Admin API
| Operation |
Endpoint |
Trigger |
| Update customer address |
PUT /customers/{id}.json |
Make.com |
| Create refund |
POST /orders/{id}/refunds.json |
Future |
2.3 Credentials
SHOPIFY_WEBHOOK_SECRET (Edge Functions)SHOPIFY_ADMIN_API_TOKEN (Make.com)
3. Seal Subscriptions
3.1 Inbound: Webhooks
| Attribute |
Value |
| Endpoint |
https://znfjpllsiuyezqlneqzr.supabase.co/functions/v1/seal-webhook-handler |
| Auth |
HMAC-SHA256 |
| SOP |
SOP-SUB-00 |
Event Types:
- subscription.created/updated/cancelled/paused/resumed
- billing_attempt.success/failed
3.2 Outbound: API Calls
Base URL: https://api.sealsubscriptions.com/v1
| Operation |
Method |
Endpoint |
| Skip delivery |
POST |
/subscriptions/{id}/skip |
| Pause |
POST |
/subscriptions/{id}/pause |
| Resume |
POST |
/subscriptions/{id}/resume |
| Change frequency |
PUT |
/subscriptions/{id} |
| Change box size |
PUT |
/subscriptions/{id} |
| Update address |
PUT |
/subscriptions/{id} |
| Cancel |
POST |
/subscriptions/{id}/cancel |
3.3 Credentials
SEAL_API_KEY (Edge Functions, Make.com)SEAL_WEBHOOK_SECRET (Edge Functions)
4. DPD Courier
4.1 Inbound: Tracking Webhooks
| Attribute |
Value |
| Receiver |
Make.com webhook |
| Processing |
Parse → match shipment → store courier_events |
| SOP |
SOP-02 |
Key Event Codes:
- COLLECTED - Parcel collected
- IN_TRANSIT - In transit
- OUT_FOR_DELIVERY - With driver
- DELIVERED - Successfully delivered
- DELIVERY_FAILED - Exception
- RETURNED - Returned to sender
Exception Handling:
- DELIVERY_FAILED → Customer email with redelivery options
- DELAYED → Proactive delay notice
- RETURNED → Alert #ops-urgent
5. Customer.io
5.1 Track API (Events)
| Attribute |
Value |
| Endpoint |
https://track.customer.io/api/v1/customers/{id}/events |
| Auth |
Basic (Site ID + API Key) |
| Trigger |
Make.com (Event Bridge) |
5.2 Transactional API (Direct Send)
| Attribute |
Value |
| Endpoint |
https://api.customer.io/v1/send/email |
| Auth |
Bearer (App API Key) |
| Trigger |
send-support-email Edge Function |
Email Threading:
- Add In-Reply-To and References headers
- Customer sees threaded conversation
5.3 Credentials
CUSTOMERIO_SITE_ID (Make.com)CUSTOMERIO_API_KEY (Make.com)CUSTOMERIO_APP_API_KEY (Edge Functions)
6. Gmail
6.1 Support Inbox Watch
| Attribute |
Value |
| Inbox |
support@protocolraw.co.uk |
| Trigger |
Make.com Gmail module |
| Scenario |
CS-01: Email Triage |
| SOP |
SOP-CS-01 |
Processing: Extract subject, body, Message-ID → cs-agent-triage
6.2 Lab Results Watch
| Attribute |
Value |
| Filter |
Emails from lab domains |
| Scenario |
Lab Results Processing |
| SOP |
SOP-01 |
Processing: Extract PDF → OpenAI GPT-4o → parse results → update batch
7. OpenAI
7.1 GPT-4o Vision (Lab PDF Parsing)
| Attribute |
Value |
| Model |
gpt-4o |
| Input |
Lab result PDF (base64) |
| Output |
Structured JSON with test results |
| SOP |
SOP-01 |
7.2 text-embedding-3-small (KB Search)
| Attribute |
Value |
| Model |
text-embedding-3-small |
| Dimensions |
1536 |
| Usage |
Embed query → pgvector similarity search |
| SOP |
SOP-AI-KB-01 |
7.3 Credentials
OPENAI_API_KEY (Make.com, Edge Functions)
8. Anthropic Claude
8.1 Support Classification
| Attribute |
Value |
| Model |
claude-sonnet-4-20250514 |
| Endpoint |
https://api.anthropic.com/v1/messages |
| Max Tokens |
4096 |
| Timeout |
30 seconds |
| SOP |
SOP-CS-03 |
Output:
- classification (issue type)
- intent (customer goal)
- confidence (0-1)
- draft_response (AI-generated)
- reasoning (explanation)
8.2 Credentials
ANTHROPIC_API_KEY (Edge Functions)
9. Slack
9.1 Channels
| Channel |
Purpose |
Severity |
| #ops-alerts |
Standard alerts |
Warning |
| #ops-urgent |
Critical issues |
Critical |
| #daily-ops |
Daily digest |
Info |
Uses Slack Block Kit for rich formatting with fields.
9.3 Credentials
SLACK_OPS_ALERTS_WEBHOOK (Edge Functions)SLACK_OPS_URGENT_WEBHOOK (Edge Functions)SLACK_DAILY_OPS_WEBHOOK (Edge Functions)
10. Browserless
10.1 PDF Generation
| Attribute |
Value |
| Endpoint |
https://chrome.browserless.io/pdf |
| Usage |
Pouch label PDFs for co-packer |
| SOP |
SOP-01 |
10.2 Credentials
BROWSERLESS_API_KEY (Edge Functions)
11. Resend
11.1 Partner Emails
| Attribute |
Value |
| Endpoint |
https://api.resend.com/emails |
| Usage |
Co-packer notification with label PDF |
| SOP |
SOP-01 |
11.2 Credentials
RESEND_API_KEY (Edge Functions)
12. OpenWeatherMap
12.1 Forecast API
| Attribute |
Value |
| Endpoint |
https://api.openweathermap.org/data/2.5/forecast |
| Usage |
Get max temp for PCM calculation |
| SOP |
SOP-PACK-01 |
12.2 Credentials
OPENWEATHERMAP_API_KEY (Edge Functions)
13.1 Connection
| Attribute |
Value |
| Type |
PostgreSQL (direct to Supabase) |
| Host |
db.znfjpllsiuyezqlneqzr.supabase.co |
| Schema |
raw_ops |
| User |
metabase_readonly |
13.2 Dashboards
- Pack Queue with PCM requirements
- Batch Status & Inventory
- Fulfillment Performance
- CAC & LTV Metrics
- Support Metrics
14. Infrastructure
14.1 Supabase
| Attribute |
Value |
| Project URL |
https://znfjpllsiuyezqlneqzr.supabase.co |
| Region |
eu-west-2 (London) |
| Plan |
Pro |
14.2 Cloudflare
| Site |
URL |
Auth |
| Ops Portal |
ops.protocolraw.co.uk |
Google OAuth |
| Customer Portal |
portal.protocolraw.co.uk |
Shopify token |
| Proof Portal |
proof.protocolraw.co.uk |
Public |
15. Credential Inventory
Edge Function Secrets
| Secret |
Integration |
SHOPIFY_WEBHOOK_SECRET |
Shopify |
SEAL_API_KEY |
Seal |
SEAL_WEBHOOK_SECRET |
Seal |
ANTHROPIC_API_KEY |
Claude |
OPENAI_API_KEY |
OpenAI |
CUSTOMERIO_APP_API_KEY |
Customer.io |
RESEND_API_KEY |
Resend |
BROWSERLESS_API_KEY |
Browserless |
OPENWEATHERMAP_API_KEY |
OpenWeatherMap |
SLACK_OPS_ALERTS_WEBHOOK |
Slack |
SLACK_OPS_URGENT_WEBHOOK |
Slack |
SLACK_DAILY_OPS_WEBHOOK |
Slack |
AGENT_INTERNAL_SECRET |
cs-agent-triage |
| Connection |
Integration |
| Supabase |
Database |
| Shopify |
Admin API |
| Seal |
Subscription API |
| Gmail |
Inbox monitoring |
| Customer.io |
Track API |
| Slack |
Messaging |
| OpenAI |
GPT-4o |
Protocol Raw — Verified safe, batch by batch.