Zapier Integration Guide

1. Integration Status & Scope Boundary

The integration connects to FTT's deterministic cancellation infrastructure using direct, scoped API keys and signed HTTP callbacks.

2. Authentication Flow

Zapier integrations authenticate using scoped, revocable API keys passed in the standard HTTP Authorization header:

Authorization: Bearer <FTT_API_KEY>

Callers may supply optional caller identification headers for tracking and audit logs:

X-FTT-Caller-ID: zapier-app
X-FTT-Caller-Type: THIRD_PARTY_APP

Verify Connection Identity

Use the identity endpoint to verify API key validity, account binding, and granted scopes:

curl -X GET "https://api.freetrialterminator.com/api/v1/integrations/zapier/identity" \
  -H "Authorization: Bearer $FTT_API_KEY" \
  -H "X-Request-Id: $(uuidgen)"

Expected Response (200 OK):

{
  "success": true,
  "data": {
    "integration": "zapier",
    "environment": "staging",
    "connection_label": "FTT Staging",
    "connection_id": "018f3a5e-99e2-763d-82d1-0f72ec8b49e2",
    "scopes": ["cancellations:read", "status:read"]
  },
  "case_id": "UNKNOWN_CASE",
  "current_state": "DETECTED",
  "reason_for_state": "UNKNOWN_REASON",
  "last_event": {
    "event_id": "UNKNOWN_EVENT_ID",
    "event_type": "UNKNOWN_EVENT",
    "event_at": "2026-10-10T12:00:00.000Z",
    "correlation_id": "UNKNOWN_CORRELATION_ID"
  },
  "explainability": {
    "decision_history_url": null,
    "decision_source": "SYSTEM_INFERRED"
  },
  "timestamp": "2026-10-10T12:00:00.000Z"
}

3. Required API-Key Scopes

Free Trial Terminator enforces granular least-privilege permission scopes. Each API request validates required scopes:

4. Supported Actions Catalog

Zapier actions correspond directly to authorized endpoints in the public OpenAPI 3.1 specification:

5. Supported Triggers Catalog

FTT projects six approved canonical trigger events via transactional outbox subscriptions:

6. Human Attention & Admin Authority

The cancellation.human_attention_required trigger notifies automated workflows that manual operational review or dead-letter escalation is underway.

7. Webhook Failure Isolation

Free Trial Terminator implements strict failure isolation between external webhook delivery and canonical core business state:

• Outbox Segregation: Webhook deliveries are queued into a transactional outbox table atomically with state transitions.
• Delivery Failure Boundaries: External HTTP timeouts, 5xx server errors on Zapier endpoints, DNS resolution errors, or retry exhaustion update only the webhook delivery log status (FAILED / EXHAUSTED).
• State Immutability: A webhook delivery failure never alters, rolls back, or erases canonical case state, cancellation proof, audit EventLog truth, or confidence score.
• Killswitch Safety: Disabling the Zapier integration halts outbound webhook delivery without interrupting internal cancellation execution.

8. ACTION_REQUIRED Semantics & Non-Completion Rule

When a cancellation requires direct customer interaction (e.g., SMS two-factor verification, phone confirmation callback, or proprietary provider questionnaire), the case transitions to ACTION_REQUIRED.

9. Idempotency Requirements

To prevent duplicate cancellation execution or duplicate outbox subscriptions during network retries:

• Execution Header: All POST /execute requests require an Idempotency-Key header containing a unique UUIDv4 string.
• Safe Replays: Repeating a request with the exact same idempotency key and body returns the original cached response.
• Key Conflict Detection: Reusing the same key with different payload parameters returns IDEMPOTENCY_KEY_REUSED (409).
• Concurrent In-Progress Guard: Concurrent execution calls with the same key return IDEMPOTENCY_REQUEST_IN_PROGRESS (409).
• Webhook Deduplication: Webhook registrations enforce uniqueness on (webhook_id, event_id, event_type) to guarantee at-least-once outbox processing without duplicate event delivery.

10. Webhook Signature Verification

Every outbound webhook delivery includes cryptographic headers signed with your webhook endpoint secret:

Verification Code Example (Node.js)

import crypto from 'node:crypto';

export function verifyWebhookSignature({
  rawBody,
  signatureHeader,
  timestampHeader,
  webhookSecret,
  toleranceSeconds = 300,
}: {
  rawBody: string;
  signatureHeader: string;
  timestampHeader: string;
  webhookSecret: string;
  toleranceSeconds?: number;
}): boolean {
  const now = Math.floor(Date.now() / 1000);
  const ts = parseInt(timestampHeader, 10);
  if (Number.isNaN(ts) || Math.abs(now - ts) > toleranceSeconds) {
    return false; // Stale timestamp outside tolerance window
  }

  const expectedSignature = 'v1=' + crypto
    .createHmac('sha256', webhookSecret)
    .update(`${timestampHeader}.${rawBody}`)
    .digest('hex');

  const providedBuf = Buffer.from(signatureHeader, 'utf8');
  const expectedBuf = Buffer.from(expectedSignature, 'utf8');

  if (providedBuf.length !== expectedBuf.length) {
    return false;
  }

  return crypto.timingSafeEqual(providedBuf, expectedBuf);
}

11. Replay Protection & Retry Backoff

Consuming endpoints and Zapier receivers must follow these delivery guidelines:

• Replay Rejection: Store recent X-FTT-Event-Id values in a key-value cache (e.g., Redis with 24-hour TTL). If an event ID has already been processed, return HTTP 200 immediately without reprocessing business actions.
• Retry Backoff Schedule: FTT retries temporary delivery failures (HTTP 429, 500, 502, 503, 504, or network timeouts) using jittered exponential backoff with an initial delay of 15 seconds (nominal retries: 15s, 30s, 60s, 120s with ±20% jitter) capped at 1 hour, for up to 5 total attempts before terminal failure.
• Rate Limit Honor: If your receiver responds with HTTP 429 or 503 containing a valid Retry-After header, FTT pauses delivery retries for that duration.
• Terminal Rejection: Client errors (HTTP 400, 401, 403, 404, 422, SSRF rejections) are treated as terminal; delivery is marked permanently failed without retry.

12. Asynchronous Status Polling Example

When webhooks cannot be utilized, Zapier polling triggers should retrieve status via the canonical case endpoint using an owned case ID:

curl -X GET "https://api.freetrialterminator.com/api/v1/cancellations/c9b1f2e0-47b2-4d1a-8c76-52f10b7f0001" \
  -H "Authorization: Bearer $FTT_API_KEY" \
  -H "X-Request-Id: $(uuidgen)"

Response Example (AgenticCaseResponse):

{
  "success": true,
  "data": {
    "case_id": "c9b1f2e0-47b2-4d1a-8c76-52f10b7f0001",
    "status": "CONFIRMED",
    "safe_to_retry": false,
    "retry_count": 0,
    "next_action_type": null,
    "blocking_condition": null,
    "reason_for_state": "PROVIDER_CONFIRMED"
  },
  "case_id": "c9b1f2e0-47b2-4d1a-8c76-52f10b7f0001",
  "current_state": "CONFIRMED",
  "reason_for_state": "PROVIDER_CONFIRMED",
  "last_event": {
    "event_id": "evt_018f3a5e99e2",
    "event_type": "cancellation.completed",
    "event_at": "2026-10-15T12:04:30.000Z",
    "correlation_id": "corr_018f3a5e99e2"
  },
  "explainability": {
    "decision_history_url": null,
    "decision_source": "SYSTEM_INFERRED"
  },
  "timestamp": "2026-10-15T12:04:30.000Z"
}

To read the sanitized cancellation proof after status reaches CONFIRMED (the response includes the X-Request-Id tracking header):

curl -X GET "https://api.freetrialterminator.com/api/v1/cancellations/c9b1f2e0-47b2-4d1a-8c76-52f10b7f0001/proof" \
  -H "Authorization: Bearer $FTT_API_KEY" \
  -H "X-Request-Id: $(uuidgen)"

Response Example (CancellationProofResponse):

{
  "success": true,
  "data": {
    "schema_version": "2.0",
    "case_id": "c9b1f2e0-47b2-4d1a-8c76-52f10b7f0001",
    "current_state": "CONFIRMED",
    "reason_for_state": "PROVIDER_CONFIRMED",
    "proof_type": "CONFIRMED_CANCELLATION",
    "proof_classification": "CONFIRMED_CANCELLATION",
    "proof_source": "ADMIN_VERIFIED",
    "outcome_status": "CONFIRMED",
    "verification_method": "PROVIDER_ACCOUNT_PAGE",
    "verified_at": "2026-10-15T12:04:30.000Z",
    "artifact_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "confidence_band": "HIGH"
  }
}

Proof responses return exactly these fields and nothing else. No storage location, signed URL, raw artifact, admin note, or internal lineage metadata is ever exposed; artifact_sha256 is populated only for a validated admin-verified proof.

13. Structured Error Registry Table

All API errors return consistent JSON envelopes containing a stable error_code and correlation identifier:

14. Privacy & PII Safeguards

Free Trial Terminator maintains strict perimeter privacy boundaries. All Zapier payloads, event emissions, and webhook envelopes utilize explicit schema allowlists:

• Never Exposed: User passwords, banking credentials, full credit card numbers, CVVs, raw provider session cookies, raw conversational chat transcripts, or prompt history.
• Internal Engine Redaction: Internal Provider Intelligence heuristic formulas, private anti-bot evasion techniques, and raw scraping telemetry are strictly excluded from all Zapier responses.
• Safe Delivery Payloads: Webhook envelopes and status responses provide only authorized identifiers (case_id, provider_id), canonical state enum strings, high-level outcome reasons, and verified evidence URLs.

15. Limitations & Governance Statement

Documentation version e15d-z01.v1 against contract version 2026-10-11.c15b-z01.v1. Last updated October 16, 2026.