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.
Webhooks
Section titled “Webhooks”| 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_idis unique because Stripe redeliverspayment_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.
Ops endpoints
Section titled “Ops endpoints”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.
Uploads
Section titled “Uploads”| 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.
Adding an endpoint
Section titled “Adding an endpoint”- Handler in
packages/core/src/http/. - Mount it in the
mountsarray inapps/api/src/index.ts. - Only if the web origin must serve it too, add the path to
PROXIED_PREFIXESorPROXIED_EXACTinapps/web/src/proxy.ts.
Nothing with business logic goes in apps/web/src/app/**/route.ts.
