Skip to content

Webhooks, cron and uploads

Handlers live in packages/core/src/http/ and are mounted in the mounts array in apps/api/src/index.ts. The web app serves a few of them too, through one-line re-exports, until every external caller points at the API host.

Endpoint Source
POST /api/webhooks/stripe Stripe
POST /api/webhooks/autosend Autosend (email delivery events)
POST /api/webhooks/whatsapp apps/whatsapp-gateway

Rules for the Stripe webhook, learned the hard way:

  • Idempotency is not optional. payments.stripe_payment_intent_id is unique because Stripe redelivers payment_intent.succeeded.
  • Never throw on a structural problem. Capture it, log it, return 200. A 500 makes Stripe retry for three days against something that will never resolve.
  • A succeeded PaymentIntent always leaves a row — a booking with a payment, or an orphan payment flagged for review.

Point Autosend at the API host directly: https://api.tcgkl.com/api/webhooks/autosend. Through tcgkl.com the web app proxies the event to the API, so a deploy of either app drops deliveries. Autosend retries only three times over about 35 seconds, shorter than a deploy window, so events lost there (including unsubscribes and spam reports) are not redelivered. Avoid deploying during campaign sends.

The WhatsApp gateway spools webhooks it cannot deliver and retries, so a deploy window does not lose inbound messages. It posts through Traefik rather than a container name so a restarting replica cannot black-hole traffic.

Coolify scheduled tasks POST to these:

Endpoint Job
/api/cron/cleanup-expired Expire stale holds, send the abandonment email
/api/cron/send-reminders Booking reminders
/api/cron/auction-close Close auctions
/api/cron/auction-lifecycle Auction state transitions
/api/cron/auction-chat-retention Trim auction chat history
/api/cron/sync-emails Email sync
/api/cron/cdp-nightly Nightly CDP build
/api/cron/con2026-outreach Every minute: expire/reconcile WhatsApp reply drafts, then at most one paced convention-outreach send — see WhatsApp outreach
/api/cron/instagram-sync Every 30 min: pull Instagram DMs into the admin inbox
/api/cron/petition-retention Daily 18:30 UTC (02:30 MYT): petition deletion promises — see Petition flow
/api/cron/send-scheduled-push Every minute: dispatch due scheduled mobile push campaigns via FCM

All of them require Authorization: Bearer $CRON_SECRET (unset → 500, mismatch → 401) and are wrapped in monitoredCron, which sends one Sentry Cron check-in per run. Schedules and monitor slugs are listed in docs/deployment-strategy.md.

cleanup-expired is part of the payment path — changing it means an entry in docs/booking-payments/decisions.md.

Server-to-server endpoints for the staff WhatsApp assistant, token-authenticated rather than session-authenticated, mounted on the API and proxied from the web origin under /api/ops/.

Endpoint Token
POST /api/ops/whatsapp-reply OPS_WHATSAPP_TOKEN
POST /api/ops/inbox/mark-done, POST /api/ops/crm/status OPS_WHATSAPP_TOKEN
/api/ops/sales-desk/* (drafts, decision, done, reply, ticket-update, sales-report) SALES_DESK_TOKEN (≥ 32 chars)

Behaviour and limits: WhatsApp outreach and the Sales Desk; full contract in docs/whatsapp-assistant/sales-desk-api.md.

Endpoint Purpose
POST /api/upload User upload
POST /api/admin/upload Admin upload
POST /api/admin/upload/presign Presigned R2 URL
POST /api/profile/avatar Avatar

Storage is Cloudflare R2. CLOUDFLARE_R2_BUCKET differs per environment (tcgkl / tcgkl-beta) and CLOUDFLARE_R2_PUBLIC_URL has no trailing slash — a double slash in an asset URL is almost always that.

  1. Handler in packages/core/src/http/.
  2. Mount it in the mounts array in apps/api/src/index.ts.
  3. Only if the web origin must serve it too, add the path to PROXIED_PREFIXES or PROXIED_EXACT in apps/web/src/proxy.ts.

Nothing with business logic goes in apps/web/src/app/**/route.ts.