OAuth & Webhook Flows

This page describes implemented flows in apps/api and apps/web.

Square Connect Flow

OAuth State Security

State is HMAC-signed and expiring (10-minute TTL), not trusted blindly.

If state validation fails, callback redirects with failure diagnostics.

OAuth Host Safety

Authorization URL host is hard-guarded to:

• connect.squareupsandbox.com
• connect.squareup.com

Web client also validates/normalizes URL before redirect.

Webhook Flow

Route: POST /api/v1/webhooks/square

This is a fast-ack model with asynchronous processing to keep provider retries low.

Poll Fallback

Route: POST /api/v1/internal/cron/square-poll-payments

• protected by X-Cron-Secret
• scans active Square connections
• refreshes expiring access tokens when needed
• calls ListPayments using watermark checkpoint
• executes same ingestion path as webhooks

Clover Status

Clover endpoints exist as placeholders:

• callback route redirects with not-implemented status
• webhook route currently acknowledges only

Deep Dives

• POS Integrations
• Ingestion, Wallet, and Rewards
• API Reference