Triggers

Every agent needs a trigger — something that starts a run. Papayya supports three trigger modes that cover every production pattern: on-demand, recurring, and event-driven.

API (on-demand)

The most common trigger. Your backend calls the Papayya API when a user action or internal event requires an agent run.

When to use: User-initiated workflows, batch processing, anything where your code decides when to run.

Real-world examples

SaaS product with AI features — a user clicks "Analyze competitors" in your app:

# Your backend handler
def handle_analysis_request(user_id, query):
    run = papayya.runs.create(
        agent_id="research-agent",
        input=query,
        budget_cents=100,
        callback_url=f"https://api.yourapp.com/runs/complete"
    )
    # Return immediately — Papayya runs the agent in the background
    return {"run_id": run.id, "status": "processing"}

Batch processing — enrich 500 leads overnight:

for lead in leads:
    papayya.runs.create(
        agent_id="lead-enrichment",
        input=json.dumps({"company": lead.company, "domain": lead.domain}),
        budget_cents=50,
    )
# Papayya handles concurrency limits, budgets, and retries

Internal tools — trigger from CLI or scripts:

curl -X POST https://api.getpapayya.com/v1/runs \
  -H "X-Api-Key: cpk_..." \
  -d '{
    "agent_id": "code-reviewer",
    "input": "Review PR #342 in papayya",
    "budget_cents": 200
  }'

Callback URL

Pass a callback_url when triggering a run, and Papayya will POST the result when it finishes. This eliminates polling — fire and forget.

{
  "agent_id": "...",
  "input": "...",
  "callback_url": "https://your-api.com/webhook/run-complete"
}

The callback payload includes run status, output, token counts, cost, and error details. Retried up to 3 times with exponential backoff.

Schedules (recurring)

Cron-based triggers for agents that need to run on a regular cadence. Each execution creates a new run with the configured input and constraints.

When to use: Monitoring, reporting, periodic data processing — anything that runs on a clock.

Real-world examples

Daily competitor monitoring:

papayya schedule create \
  --agent-id competitor-monitor \
  --cron "0 9 * * 1-5" \
  --timezone "America/Toronto" \
  --input "Check competitor pricing pages for changes" \
  --budget-cents 200

Runs every weekday at 9am. The agent scrapes competitor pages, compares with yesterday, and sends a Slack alert if anything changed.

Hourly data pipeline:

papayya schedule create \
  --agent-id crm-enrichment \
  --cron "0 * * * *" \
  --input "Enrich new CRM records from the last hour" \
  --budget-cents 500

Every hour, the agent queries your CRM for new records, enriches them with AI, and writes the results back.

Weekly compliance scan:

papayya schedule create \
  --agent-id compliance-scanner \
  --cron "0 2 * * 0" \
  --input "Scan all active contracts for compliance issues" \
  --budget-cents 1000

Every Sunday at 2am, scans documents and flags potential issues for the legal team on Monday morning.

Schedule fields

Managing schedules

papayya schedule list --agent-id <id>
papayya schedule disable <schedule-id>
papayya schedule enable <schedule-id>
papayya schedule update <schedule-id> --cron "0 */6 * * *"
papayya schedule delete <schedule-id>

Budget and step limits apply to each individual run, not the schedule as a whole. If a scheduled run hits its budget, it stops — the next scheduled run starts fresh.

Webhooks (event-driven)

Webhooks let external systems trigger agent runs via HTTP. Create a webhook for an agent, and any service that can make an HTTP POST can start a run.

When to use: Reacting to external events — GitHub pushes, Stripe payments, Slack messages, form submissions.

Real-world examples

GitHub PR review agent:

# Create the webhook
papayya webhook create --agent-id pr-reviewer --name "GitHub Push"
# Returns: webhook URL + token
 
# In GitHub repo settings, add the webhook URL
# When a PR is opened, GitHub POSTs the event payload
# Papayya starts a run with the PR data as input

The agent receives the full GitHub event payload, fetches the diff, analyzes the code, and posts review comments.

Stripe payment processing:

papayya webhook create --agent-id invoice-processor --name "Stripe Invoice"

Configure Stripe to send invoice.paid events to the webhook URL. The agent receives the invoice data, generates a personalized onboarding email, and triggers your email service.

Slack support agent:

papayya webhook create --agent-id support-agent --name "Slack Support"

When someone posts in #support, a Slack workflow sends the message to Papayya. The agent researches the issue in your docs and knowledge base, then posts a drafted response back to the channel.

Creating and using webhooks

# Create
papayya webhook create --agent-id <id> --name "My Webhook"
 
# Returns a webhook ID and token (shown once)
# Trigger URL: POST /v1/webhooks/{webhookId}/trigger
# Auth: Authorization: Bearer whk_...

The request body becomes the run's input — any valid JSON or plain text. You can also pass a callback URL via header:

curl -X POST https://api.getpapayya.com/v1/webhooks/<id>/trigger \
  -H "Authorization: Bearer whk_..." \
  -H "X-Callback-URL: https://your-api.com/done" \
  -d '{"event": "push", "repo": "papayya", "branch": "main"}'

Managing webhooks

papayya webhook list --agent-id <id>
papayya webhook delete <webhook-id>

Choosing a trigger

All three triggers share the same execution guarantees: crash recovery, budget enforcement, step-level tracing, and dashboard visibility. Every run — whether triggered by an API call, a cron schedule, or a GitHub push — goes through the same pipeline.

You can combine triggers for the same agent. A competitor monitoring agent might run on a daily schedule and be triggerable via API for ad-hoc checks.