Skip to main content

Scheduled generation

Problem: A cron fires weekly. It should generate a branded status deck from yesterday’s KPIs and post the canvas URL to a Slack channel. No human in the loop.

Primitives

  • POST /v1/tasks with callback_url + idempotency_key
  • Webhook handler verifies signature and posts to Slack
  • (Optional) POST /v1/canvases/{id}/export if you want a PPTX link, not just the canvas URL

Pattern

Cron → start task with a stable idempotency_key → return immediately. The webhook fires 2–10 minutes later and does the Slack post.

TypeScript (Node 20+)

Cron entry point:
Webhook handler (Express):

Python (FastAPI + httpx)

Cron entry point:
Webhook handler (FastAPI):

Gotchas

  • Prefer: wait=30 is the wrong tool here. Design tasks take 2–10 min. The cron would time out, and the webhook still fires anyway. Use the callback pattern.
  • idempotency_key must be stable and unique per cron fire. "weekly-deck:2026-W17" is good. "weekly-deck" alone is a landmine (every week reuses the same key → same task every time).
  • callback_url is API-key-auth only. The cron needs a real moda_live_… key.
  • Slow webhook handlers get retried. Stay under 30s wall time by enqueueing async.
  • On task.failed, check data.error.retryable — transient failures may retry inside Moda automatically; permanent ones won’t. Either way, notify a channel — failures silently swallowed are the worst case.

See also