Scheduling & webhooks

Interval vs. webhook

Every schedule is one of two trigger types.

• Interval — Prowl runs the report on a cadence you set. cadence is daily, weekly, or monthly; run_at_hour is the UTC hour 0-23 (default 8, i.e. 08:00 UTC, always on the hour). Interval jobs get a computed next_run_at.
• Webhook — Prowl returns a private trigger URL. The report runs when you POST to that URL, on your own schedule (cron, CI, an app event). Webhook jobs ignore cadence and run_at_hour.

Both types share the same options: execution_mode is basic, deep, or max (deep and max require an active subscription, checked fresh each time the job fires — a lapsed subscription downgrades the run to basic rather than failing it); an optional playbook_id fixes the report structure; and the query is capped at 32,000 characters (tunable via PROWL_SCHEDULE_MAX_QUERY_CHARS). Each account may hold at most 20 schedules total — the same shared limit applies whether you create them over REST or via MCP.

Create and manage a schedule

Two surfaces, one backend — schedules created either way share the same 20-per-account limit and behave identically.

REST API (uses your account auth):

• POST /api/schedules — create; returns 201 with the schedule JSON (webhook jobs include a webhook_url).
• GET /api/schedules — list your schedules, with count and the limit (20).
• DELETE /api/schedules/{job_id} — cancel (404 if it is not yours).
• POST /api/schedules/{job_id}/resume — re-activate a paused job.

curl -X POST https://prowl.chat/api/schedules \\
  -H "Content-Type: application/json" \\
  -d '{"query": "weekly SEO recon for example.com",
       "trigger_type": "interval",
       "cadence": "weekly",
       "run_at_hour": 8,
       "execution_mode": "deep"}'

Exceeding the cap returns an error ("schedule limit reached (20)"); cancel one first.

MCP tools (need an authenticated Prowl API key): prowl_schedule_create, prowl_schedule_list, prowl_schedule_cancel, and prowl_schedule_resume. A successful prowl_schedule_create replies with the schedule id and either the next run time (interval) or the trigger URL (webhook).

Cadence examples

Interval schedules fire at run_at_hour UTC, on the hour. The first run is the next matching slot strictly after creation time.

All hours are UTC; convert from your local time when choosing run_at_hour.

Webhook trigger, payload & retries

A webhook schedule gives you a capability URL of the form POST https://prowl.chat/webhooks/schedule/<token>. Firing it by hand is the test path for scheduling — create a webhook job, POST the URL, and confirm the report lands in your account.

Request. The endpoint ignores the request body, so send an empty POST. No auth header is needed; the token in the path is the credential.

curl -X POST https://prowl.chat/webhooks/schedule/YOUR_TOKEN

Response. Prowl accepts the trigger and runs the report in the background, returning immediately:

202 Accepted
{"status": "accepted", "job_id": "..."}

Status codes.

• 202 — accepted; the report is now running server-side.
• 404 — unknown token, or the schedule is inactive/paused, or it is not a webhook job.
• 429 — rate limited. Each token allows 6 triggers per 60-second window (tunable via PROWL_WEBHOOK_RATE_LIMIT / PROWL_WEBHOOK_RATE_WINDOW_SEC); a Retry-After header tells you when to try again.
• 503 — scheduling is disabled on the server.

Retries & delivery. This webhook is inbound: you call Prowl, Prowl does not call you back. There is no outbound callback and no report payload delivered to an external URL — the finished report is stored in your account (retrieve it from your history or via the schedule's last_artifact_id). Prowl performs no automatic retry: on a 429, wait out the Retry-After window and POST again; a 202 means the run is already underway, so do not re-fire it.

Failures: pause, resume & errors

Each run records a last_status, last_run_at, and last_artifact_id, all visible when you list schedules.

• ok — report generated and stored; for interval jobs, next_run_at advances to the next slot.
• paused_insufficient_funds — at fire time the wallet could not cover the run, so the job is paused instead of looping on empty reports. Top up your balance, then re-activate it with the resume endpoint (POST /api/schedules/{job_id}/resume) or prowl_schedule_resume.
• error — a runtime failure during the run. The job stays active and next_run_at still advances, so a transient error does not retire the schedule; it simply tries again next slot.

Billing happens at fire time through the same wallet reserve/settle gate as an interactive report — a schedule never bills at creation time.

Security: the token is the secret

A webhook trigger URL is a bearer capability — anyone holding the full URL can fire the schedule (bounded only by the per-token rate limit and your wallet). Treat it like a password.

• There is no request signing. Prowl does not send an HMAC or signature header, and the trigger endpoint verifies none. The only secret is the random token embedded in the URL, so do not build signature-verification logic against it.
• Keep the URL private — store it in a secrets manager, never in client-side code or a public repo.
• To rotate a leaked URL, delete the schedule and create a new one — there is no in-place rotate. Deleting immediately invalidates the old token, and further POSTs to it return 404.