Webhooks & schedules

Accept external POSTs and fire workflows on a cron — registered as JSON manifests under .appbricx/backend/, synced into platform Postgres so the ticker and public hook router can find them.

Webhooks

Manifest

// .appbricx/backend/webhooks/lead-intake.json
{
  "id": "lead-intake",
  "name": "lead-intake",
  "workflow": "on-lead-created",
  "secret_ref": "WEBHOOK_SECRET",
  "enabled": true
}

Put the secret value in project env / vault under the name WEBHOOK_SECRET — never in the JSON file. Declare the name in secrets.refs.json.

Call it

curl -sS -X POST "$ORIGIN/hooks/$PROJECT_ID/lead-intake" \
  -H "content-type: application/json" \
  -H "x-appbricx-webhook-secret: $WEBHOOK_SECRET" \
  -d '{"email":"demo@example.com","source":"stripe"}'
# → { "ok": true, "runId": "…" }

• Public route (no browser JWT). Rate limited (~60/min/project).
• Payload lands on ctx.trigger.payload.body (plus headers metadata).
• Prefer runtime.upsert_webhook; editor create_file also syncs disk → DB.

Internal flow

1. Caddy routes /hooks/* → API.
2. Load webhook from app_runtime_webhooks (fallback: JSON file).
3. Compare secret header to env value for secret_ref.
4. enqueueWorkflowRun with triggerType: "webhook".

Schedules (cron)

Manifest

// .appbricx/backend/schedules/nightly-lead-digest.json
{
  "id": "nightly-lead-digest",
  "cron": "0 21 * * *",
  "timezone": "UTC",
  "workflow": "nightly-digest",
  "enabled": true
}

• Five-field cron (min hour dom month dow).
• Prefer runtime.upsert_schedule so next_run_at is computed in DB immediately.
• Writing the JSON via the agent also registers the row (disk → DB sync). Unchanged specs preserve next_run_at so editor polls do not delay fires.

List schedules (session JWT — editor)

GET /projects/:projectId/backend/schedules
Authorization: Bearer <platform session>

Syncs from disk first, then returns ticker state (next_run_at, enabled, cron).

Demo tip

For a social clip, temporarily set */1 * * * *, invoke the workflow with runtime.workflows.invoke / Backend → Test, then show the nightly cron in the file tree.

Internal flow

1. Process boot starts the schedule ticker (~15s tick).
2. Due rows in app_runtime_schedules are leased and enqueue the named workflow with triggerType: "cron".
3. next_run_at advances to the next cron occurrence.

Related: Workflows · Topics & CDC