Openhands Automation

OpenHands Automations

Create and manage automations that run inside an OpenHands agent server — triggered by cron schedules or webhook events (GitHub, custom services). Windows PowerShell equivalents for the automation API curl examples and shell-variable conventions are in references/windows.md.

Automation Creation Process

The agent must follow these steps when creating an automation:

• Quickly check that you can access the correct automations backend using the auth mechanism below
• Quickly check that you can access any necessary integrations (e.g. GitHub, Slack); if access fails, inform the user and stop
• Ask the user for any necessary information, e.g. if you need the name of a Slack channel or GitHub repo to proceed
• Write the code or prompt that will be sent to the automations backend inside the current workspace
• Show the code to the user with the canvas_ui tool if available, otherwise present it in a fenced code block in your reply
• Message the user with a concise summary of how the automation will behave, and ask if they are ready to deploy it

Architecture

Two components work together to run automations:

Automation Service (API at OPENHANDS_HOST/api/automation/v1) Manages the when: holds automation definitions, schedules cron-triggered runs, dispatches webhook-triggered runs, and receives completion callbacks to mark runs as done. This is the API you call to create, update, and manage automations.

Agent Server (accessible as AGENT_SERVER_URL inside script runs) Manages the what: the runtime environment where automation scripts execute and where conversations (AI agent interactions with tools, bash, file editing, etc.) run. When a run is triggered, the automation service uploads the automation's tarball to the agent server, which unpacks and runs the entrypoint script. The script connects back to the agent server using AGENT_SERVER_URL and a session API key to start, monitor, and stop conversations.

The agent server typically runs inside a sandbox (a Docker or Kubernetes container). Some deployments use sandboxless mode, where the agent server runs directly on a host.

Key environment variables:

⚠️ CRITICAL — Agent behavior rules:

0. Does this task need an LLM at all? Check first. Before picking a preset, ask whether the task actually requires reasoning, judgment, summarization, or open-ended tool use. If it is fully deterministic — fixed data transforms, scheduled HTTP calls, healthcheck pings, file rotation, picking from a known list, posting a templated message — an LLM-driven preset is overkill. Every run will consume LLM tokens, which adds up fast at high frequencies (every 5 min ≈ 288 runs/day). Surface the trade-off to the user and offer the custom-script path (see references/custom-automation.md) as the cheaper, more reliable option. Be especially careful for cron schedules tighter than hourly.

   Instant-recognition patterns — these are always deterministic, never use an LLM preset:

   • "post a quote / message / fact every N minutes" (rotating from a list)
   • "send a scheduled reminder / standup / digest"
   • "ping a health-check URL on a schedule"
   • "post to Slack / webhook every N minutes"
   • Any task where the full output could be written as a static template right now

1. For LLM-appropriate work, default to preset endpoints. They handle all SDK boilerplate, tarball packaging, and upload automatically:

   • Prompt preset (POST /v1/preset/prompt) — for tasks expressed as a natural language prompt that benefit from agent reasoning
   • Plugin preset (POST /v1/preset/plugin) — when plugins with skills, MCP configs, or commands are needed

2. Present the options, then build the one the user picks. Whenever rule 0 applies, or neither preset is a clean fit (custom Python dependencies, a non-Python entrypoint, a multi-file project, direct SDK lifecycle control), lay the choices out side by side with a one-line note on cost and reliability for each, and let the user choose:

   • Prompt preset - natural language prompt execution (LLM-driven)
   • Plugin preset - load plugins with extended capabilities (skills, MCP, hooks, commands)
   • Custom script - full control over code, with or without an LLM; see references/custom-automation.md

   Do not silently fall back to either side. The "ready to deploy?" confirmation in the creation process applies to every path equally; a custom script needs no extra permission beyond it, and a preset gets no pass on it.

3. Building a custom script: follow references/custom-automation.md for tarball packaging, validation, and upload. The Custom Script Example (No LLM) below shows the whole flow end to end.

4. Before suggesting event-triggered (webhook) automations, check whether the deployment is publicly reachable. Check RUNTIME_URL. Webhooks require an internet-accessible URL so that external services (GitHub, Slack, Linear, etc.) can deliver events to the automation service. If RUNTIME_URL is unset, empty, or resolves to a local or private address (localhost, 127.0.0.1, 0.0.0.0, or any RFC 1918 range: 10.x.x.x, 192.168.x.x, 172.16–31.x.x), the service cannot receive inbound webhook traffic from the public internet. In that case:

   • Recommend a cron-based polling automation instead. Have the automation run on a schedule and call the external service's API (e.g., the GitHub REST API) to check for new events since the last run.
   • Explain the limitation clearly to the user: "Because this is a local deployment, external services can't reach the webhook endpoint. I'll set up a polling automation using a cron schedule instead."

No-LLM Script Helpers

When building a deterministic custom script, these two stdlib-only functions are required. Copy them verbatim - they use variables injected by the automation service: SESSION_API_KEY, plus AGENT_SERVER_URL on a local Agent Canvas or OPENHANDS_CLOUD_API_URL and SANDBOX_ID on OpenHands Cloud and Enterprise.

import json, os, urllib.request

def get_secret(name):
    """Fetch a named secret: from the agent server when AGENT_SERVER_URL is set, else from the OpenHands API."""
    url = os.environ.get("AGENT_SERVER_URL", "").rstrip("/")
    key = os.environ.get("SESSION_API_KEY") or os.environ.get("OH_SESSION_API_KEYS_0", "")
    if url:  # local Agent Canvas
        url = f"{url}/api/settings/secrets/{name}"
    else:  # OpenHands Cloud / Enterprise
        api = os.environ["OPENHANDS_CLOUD_API_URL"].rstrip("/")
        url = f"{api}/api/v1/sandboxes/{os.environ['SANDBOX_ID']}/settings/secrets/{name}"
    with urllib.request.urlopen(urllib.request.Request(
        url, headers={"X-Session-API-Key": key}
    )) as r:
        return r.read().decode().strip()

def fire_callback(status="COMPLETED", error=None):
    """Signal run completion. MUST be called on every exit path — success AND error."""
    url = os.environ.get("AUTOMATION_CALLBACK_URL", "")
    if not url: return
    body = {"status": status, "run_id": os.environ.get("AUTOMATION_RUN_ID", "")}
    if error: body["error"] = error
    try:
        urllib.request.urlopen(urllib.request.Request(url, data=json.dumps(body).encode(), headers={
            "Content-Type": "application/json",
            "Authorization": f"Bearer {os.environ.get('AUTOMATION_CALLBACK_API_KEY', '')}",
        }))
    except Exception as e: print(f"Callback error: {e}")

Entrypoint must be python3 main.py (no setup.sh needed). Wrap your main logic in try/except and call fire_callback("FAILED", str(e)) in the except block.

State persistence between runs — polling automations that track a "last processed" timestamp or active conversation IDs must use the built-in KV store rather than local files. Local files are lost when a run ends on a cloud pod. The KV store is available when AUTOMATION_KV_TOKEN is injected into the run environment. See references/custom-automation.md#state-persistence-kv-store for ready-to-copy kv_get / kv_set / load_state / save_state helpers.

Authentication

All requests require authentication:

• Cloud (default https://app.all-hands.dev): Bearer token:

  -H "Authorization: Bearer ${OPENHANDS_API_KEY}"

• Local Agent Canvas (http://localhost:8001): session API key through X-Session-API-Key:

  -H "X-Session-API-Key: ${OPENHANDS_AUTOMATION_API_KEY:-${SESSION_API_KEY}}"

The curl examples below show cloud Bearer authentication. For local Agent Canvas, replace that header with the X-Session-API-Key header above.

API Endpoints

Determining the API Host

Before making API calls, determine the correct host:

The automation service may run at a different URL from the agent server. In the examples throughout this skill, ${OPENHANDS_HOST} is a shell-variable convention for the automation service base URL — it is not a real environment variable. Set it from context before running any curl command:

• Look for a <HOST> value in the system prompt or runtime-services block. If present, use that URL.
• If running inside a local Agent Canvas stack and no explicit host is provided, use http://localhost:8001 for the local automation/agent-server API.
• Otherwise default to https://app.all-hands.dev.

For a local Agent Canvas server, validate the endpoint before making a mutating request and authenticate with the session key through X-Session-API-Key when that API requires it. Do not use the cloud default merely because no <HOST> value is present.

# Choose the host that matches the detected environment:
OPENHANDS_HOST="http://localhost:8001"       # local Agent Canvas
# OPENHANDS_HOST="https://app.all-hands.dev" # OpenHands Cloud

Automation Endpoints

Custom Webhook Endpoints

Trigger Types

Automations support two trigger types:

Creating Automations

Two preset endpoints simplify automation creation by handling SDK boilerplate, tarball packaging, and upload automatically:

1. Prompt Preset — Execute a natural language prompt (simple tasks)
2. Plugin Preset — Load plugins with skills, MCP configs, and commands (extended capabilities)

Prompt Preset

Use the preset/prompt endpoint for simple automations. Provide a natural language prompt describing the task.

How It Works

1. Send a prompt describing the task (e.g., "Generate a weekly status report")
2. The automation service generates a Python script that: fetches LLM config and secrets from the agent server, starts an AI agent conversation with your prompt, and sends a completion callback when done
3. The script is packaged as a tarball and the automation is registered; on each trigger, the automation service uploads the tarball to the agent server, which unpacks and runs the script inside its environment

Request

curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Automation Name",
    "prompt": "What the automation should do",
    "trigger": {
      "type": "cron",
      "schedule": "0 9 * * *",
      "timezone": "UTC"
    }
  }'

Request Fields

Cron Trigger Fields:

Event Trigger Fields:

Prompt Tips

Write the prompt as an instruction to an AI agent. The prompt executes inside a sandbox with full tool access (bash, file editing, etc.), the user's configured LLM, stored secrets, and MCP server integrations. Examples:

• "Generate a weekly status report summarizing the team's GitHub activity and post it to Slack"
• "Read yesterday's new error reports in Sentry, group them by likely root cause, and open one GitHub issue per new failure pattern with a proposed fix"
• "Go through support tickets tagged 'bug' since the last run, try to reproduce each against main, and comment on the ticket with what you found"

Each of these needs judgment: deciding what counts as a pattern, whether a reproduction succeeded, what is worth reporting. A task whose output could be written as a fixed template right now belongs in a custom script instead (see Custom Script Example (No LLM) below).

Cron Schedule

Common schedules: 0 9 * * * (daily 9 AM), 0 9 * * 1-5 (weekdays 9 AM), 0 9 * * 1 (Mondays 9 AM), 0 0 1 * * (first of month), */15 * * * * (every 15 min), 0 */6 * * * (every 6 hours).

Response (HTTP 201)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "My Automation Name",
  "trigger": {"type": "cron", "schedule": "0 9 * * *", "timezone": "UTC"},
  "enabled": true,
  "created_at": "2025-03-25T10:00:00Z"
}

Prompt Preset Examples

Daily report:

curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Report",
    "prompt": "Generate a daily status report and save it to a file in the workspace",
    "trigger": {"type": "cron", "schedule": "0 9 * * 1-5", "timezone": "America/New_York"}
  }'

Weekly dependency review:

curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Dependency Review",
    "prompt": "Check the repository dependencies for new releases. Read each changelog, open one PR with the upgrades that look safe, and list any release with breaking changes in the PR description so a human can decide on it",
    "trigger": {"type": "cron", "schedule": "0 2 * * 0", "timezone": "UTC"},
    "timeout": 1800
  }'

Custom Script Example (No LLM)

The same shape as the prompt preset, for a task that needs no reasoning: check a URL on a schedule and post to Slack only when it fails. Every run takes a moment and costs no tokens. This is the complete flow; get_secret and fire_callback are the helpers from No-LLM Script Helpers above.

mkdir healthcheck && cd healthcheck

cat > main.py << 'PYEOF'
"""Hourly health check: alert Slack on a non-200 response. No LLM, no SDK."""
import json, os, sys, urllib.request

URL = "https://api.example.com/health"
CHANNEL = "C12345678"

def get_secret(name):
    url = os.environ.get("AGENT_SERVER_URL", "").rstrip("/")
    key = os.environ.get("SESSION_API_KEY") or os.environ.get("OH_SESSION_API_KEYS_0", "")
    if url:  # local Agent Canvas
        url = f"{url}/api/settings/secrets/{name}"
    else:  # OpenHands Cloud / Enterprise
        api = os.environ["OPENHANDS_CLOUD_API_URL"].rstrip("/")
        url = f"{api}/api/v1/sandboxes/{os.environ['SANDBOX_ID']}/settings/secrets/{name}"
    req = urllib.request.Request(url,
        headers={"X-Session-API-Key": key})
    with urllib.request.urlopen(req) as r:
        return r.read().decode().strip()

def fire_callback(status="COMPLETED", error=None):
    url = os.environ.get("AUTOMATION_CALLBACK_URL", "")
    if not url: return
    body = {"status": status, "run_id": os.environ.get("AUTOMATION_RUN_ID", "")}
    if error: body["error"] = error
    req = urllib.request.Request(url, data=json.dumps(body).encode(), headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {os.environ.get('AUTOMATION_CALLBACK_API_KEY', '')}",
    })
    try: urllib.request.urlopen(req)
    except Exception as e: print(f"Callback error: {e}")

def slack(text):
    token = get_secret("SLACK_BOT_TOKEN")
    req = urllib.request.Request("https://slack.com/api/chat.postMessage",
        data=json.dumps({"channel": CHANNEL, "text": text}).encode(),
        headers={"Content-Type": "application/json", "Authorization": f"Bearer {token}"})
    urllib.request.urlopen(req)

try:
    try:
        status = urllib.request.urlopen(URL, timeout=10).status
    except Exception as e:
        status = f"error: {e}"
    if status != 200:
        slack(f":rotating_light: {URL} returned {status}")
    print(f"{URL} -> {status}")
    fire_callback("COMPLETED")
except Exception as e:
    print(f"ERROR: {e}", file=sys.stderr)
    fire_callback("FAILED", str(e))
    sys.exit(1)
PYEOF

tar -czf ../healthcheck.tar.gz .

TARBALL_PATH=$(curl -s -X POST "${OPENHANDS_HOST}/api/automation/v1/uploads?name=healthcheck" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
  -H "Content-Type: application/gzip" \
  --data-binary @../healthcheck.tar.gz | jq -r '.tarball_path')

curl -X POST "${OPENHANDS_HOST}/api/automation/v1" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Hourly Health Check\",
    \"trigger\": {\"type\": \"cron\", \"schedule\": \"0 * * * *\", \"timezone\": \"UTC\"},
    \"tarball_path\": \"$TARBALL_PATH\",
    \"entrypoint\": \"python3 main.py\"
  }"

For state between runs (last alert time, last seen event), use the KV store helpers in references/custom-automation.md#state-persistence-kv-store.

Polling as a Webhook Alternative

When the deployment cannot receive inbound webhook traffic (see rule 4), use a cron-triggered automation that calls the external service’s API on a schedule to check for new events.

Polling vs. Webhooks at a Glance

Event-Triggered Automations (Webhooks)

Event-triggered automations run when a webhook event occurs — like a GitHub PR being opened, an issue receiving a comment, or a custom service sending a notification.

Built-in Integrations

GitHub is a built-in integration — no webhook registration needed. Just create automations with "source": "github".

GitHub Event Keys

Events use the format {event_type}.{action} or just {event_type} (for events without actions like push).

Wildcards: Use * to match any action — e.g., pull_request.* matches all PR events.

Multiple patterns: The on field can be a string or array — e.g., ["push", "pull_request.opened"].

Filter Expressions (JMESPath)

Filters let you match events based on payload content using JMESPath expressions.

Available Functions

Boolean Operators

• && — AND
• || — OR
• ! — NOT

Filter Examples

// Exact match on label name
"contains(pull_request.labels[].name, 'openhands')"

// Case-insensitive mention in comment
"icontains(comment.body, '@openhands')"

// Match specific repository
"repository.full_name == 'myorg/myrepo'"

// Match any repo in an org
"glob(repository.full_name, 'myorg/*')"

// PR with 'bug' label in any org repo
"glob(repository.full_name, 'myorg/*') && contains(pull_request.labels[].name, 'bug')"

// Push to main or release branches
"glob(ref, 'refs/heads/main') || glob(ref, 'refs/heads/release/*')"

// Issue opened by a specific user
"sender.login == 'dependabot[bot]'"

// Not a draft PR
"!pull_request.draft"

Event-Triggered Examples

GitHub: Respond to @openhands mentions in comments

curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenHands Mention Responder",
    "prompt": "Analyze the issue or PR context and provide a helpful response to the user'\''s question. The comment body and context are available in the event payload.",
    "trigger": {
      "type": "event",
      "source": "github",
      "on": "issue_comment.created",
      "filter": "icontains(comment.body, '\''@openhands'\'')"
    },
    "timeout": 300
  }'

GitHub: Auto-review PRs with the "openhands" label

curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Auto Review PRs",
    "prompt": "Review this pull request for code quality, potential bugs, and best practices. Provide constructive feedback.",
    "trigger": {
      "type": "event",
      "source": "github",
      "on": "pull_request.labeled",
      "filter": "contains(pull_request.labels[].name, '\''openhands'\'')"
    }
  }'

GitHub: Flag risky changes pushed to main

curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Risky Change Watch",
    "prompt": "Review the diff of this push. If it touches authentication, billing, data migrations, or anything that changes behavior for existing users, open an issue that explains the risk in plain terms and mentions the code owners. Otherwise do nothing.",
    "trigger": {
      "type": "event",
      "source": "github",
      "on": "push",
      "filter": "ref == '\''refs/heads/main'\''"
    }
  }'

GitHub: Triage new issues in specific repos

curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Issue Triage Bot",
    "prompt": "Analyze this new issue and suggest appropriate labels. If it looks like a bug, try to identify the root cause.",
    "trigger": {
      "type": "event",
      "source": "github",
      "on": "issues.opened",
      "filter": "glob(repository.full_name, '\''myorg/*'\'')"
    }
  }'

GitHub: Respond to multiple event types

curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "PR Activity Bot",
    "prompt": "Process the PR event and take appropriate action based on the event type.",
    "trigger": {
      "type": "event",
      "source": "github",
      "on": ["pull_request.opened", "pull_request.synchronize", "pull_request.ready_for_review"]
    }
  }'

Custom Webhooks

For services other than GitHub (Linear, Stripe, Slack, etc.), register a custom webhook first.

Agent behavior:

• Always provide the curl request to the user — do not attempt to register webhooks yourself. The exception is a service skill that ships a setup script for its webhook, such as jira-issue-to-pr: the script registers both sides and keeps the signing secret out of the conversation, so run it as that skill describes.
• Ask the user: "Do you have a webhook signing secret from [service], or should the system generate one?"
  • If they have one → include webhook_secret in the request
  • If not → omit it; the response will contain a generated secret they must configure in their service

Register a Custom Webhook

curl -X POST "${OPENHANDS_HOST}/api/automation/v1/webhooks" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Linear Issues",
    "source": "linear",
    "event_key_expr": "type",
    "signature_header": "Linear-Signature",
    "webhook_secret": "your-linear-webhook-secret"
  }'

Webhook Fields

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "webhook_url": "https://app.all-hands.dev/v1/events/{org_id}/linear",
  "source": "linear",
  "enabled": true
}

Note: When you provide your own webhook_secret, it won't be echoed back in the response. If you don't provide one, the system generates a secret and returns it once — store it securely.

Manage Custom Webhooks

# List all webhooks
curl "${OPENHANDS_HOST}/api/automation/v1/webhooks" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}"

# Update a webhook
curl -X PATCH "${OPENHANDS_HOST}/api/automation/v1/webhooks/{webhook_id}" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# Rotate the signing secret
curl -X POST "${OPENHANDS_HOST}/api/automation/v1/webhooks/{webhook_id}/rotate-secret" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}"

# Delete a webhook
curl -X DELETE "${OPENHANDS_HOST}/api/automation/v1/webhooks/{webhook_id}" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}"

Custom Webhook Example: Linear

Linear sends webhooks with:

• Signature header: Linear-Signature
• Event type in payload: type field (e.g., Issue, Comment, Project)
• Action in payload: action field (e.g., create, update, remove)

# 1. Register the Linear webhook
#    - Get your webhook signing secret from Linear's webhook settings
#    - Use "Linear-Signature" as the signature header
#    - Use "type" to extract the event type from the payload
curl -X POST "${OPENHANDS_HOST}/api/automation/v1/webhooks" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Linear Issues",
    "source": "linear",
    "event_key_expr": "type",
    "signature_header": "Linear-Signature",
    "webhook_secret": "lin_wh_xxxxxxxxxxxxx"
  }'

# Response includes webhook_url — configure this in Linear:
# Settings → API → Webhooks → New webhook → paste the webhook_url

# 2. Create an automation for new Linear issues
curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Triage New Linear Issues",
    "prompt": "A new issue was created in Linear. Analyze the issue title and description, suggest appropriate labels, and add a comment with initial triage notes.",
    "trigger": {
      "type": "event",
      "source": "linear",
      "on": "Issue",
      "filter": "action == '\''create'\''"
    }
  }'

# 3. Create an automation for high-priority issue updates
curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High Priority Issue Alert",
    "prompt": "A high-priority issue was updated. Review the changes and notify the team if action is needed.",
    "trigger": {
      "type": "event",
      "source": "linear",
      "on": "Issue",
      "filter": "action == '\''update'\'' && data.priority == `1`"
    }
  }'

Custom Webhook Example: Jira Cloud

Jira Cloud sends webhooks with:

• Signature header: X-Hub-Signature (sha256= followed by the hex HMAC-SHA256 of the body), sent only when the webhook has a secret
• Event type in payload: webhookEvent field (e.g., jira:issue_created, jira:issue_updated)
• Labels as plain strings: issue.fields.labels is ["create-pr"], not a list of objects, so issue.fields.labels[].name matches nothing
• On an update, a changelog.items list naming each changed field

Only a webhook a Jira admin registers (Jira settings → System → WebHooks, or the REST API) can carry a secret. The "Send web request" action of a Jira Automation rule cannot sign its request, so it cannot deliver to a custom webhook.

When the user can supply the API token of a Jira administrator, scripts/setup_webhook.py in the jira-issue-to-pr skill registers the webhook on both sides for them, replacing step 1 and the Jira configuration below. Done by hand:

# 1. Register the Jira webhook
#    - Use "X-Hub-Signature" as the signature header
#    - Use "webhookEvent" to extract the event type from the payload
#    - Omit webhook_secret to have one generated, or pass the one Jira generated
curl -X POST "${OPENHANDS_HOST}/api/automation/v1/webhooks" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jira Cloud",
    "source": "jira",
    "event_key_expr": "webhookEvent",
    "signature_header": "X-Hub-Signature"
  }'

# Response includes webhook_url and the generated webhook_secret - configure both in Jira:
# Jira settings → System → WebHooks → Create a WebHook → paste the webhook_url and the
# secret, then select the issue events. A JQL filter such as `labels = create-pr` keeps
# unrelated issues from being sent at all.

# 2. Create an automation for issues that receive a label
#    The filter matches an issue created with the label and an update that changes the
#    labels of an issue carrying it. Without the changelog check, every later edit of a
#    labelled issue would start another run. It still fires when another label is added
#    to or removed from an issue that carries the label, so have the prompt skip an
#    issue that already has a pull request.
curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jira Issues Labelled create-pr",
    "prompt": "A Jira issue received the create-pr label. Read the issue from the event payload and open a pull request for it.",
    "trigger": {
      "type": "event",
      "source": "jira",
      "on": ["jira:issue_created", "jira:issue_updated"],
      "filter": "contains(issue.fields.labels, '\''create-pr'\'') && (webhookEvent == '\''jira:issue_created'\'' || length(changelog.items[?field == '\''labels'\''] || `[]`) > `0`)"
    }
  }'

An unsigned request to the webhook URL answers 401 Missing signature header: X-Hub-Signature; that is the webhook working, not a fault. 404 Unknown webhook source means no webhook with that source is registered for the organization in the URL.

Common Signature Headers by Service

Plugin Preset

Use the preset/plugin endpoint when you need to load one or more plugins that provide extended capabilities like skills, MCP configurations, hooks, and commands.

💡 Finding plugins: Browse the OpenHands/extensions repository for available skills and plugins. When given a broad use case, check this directory first to see if something already exists that fits your needs.

How It Works

1. Specify one or more plugins (from GitHub repos, git URLs, or monorepo subdirectories)
2. Provide a prompt that can invoke plugin commands (e.g., /plugin-name:command)
3. The service generates SDK boilerplate that loads all plugins at runtime, creates a conversation with plugin capabilities, and executes the prompt
4. The service packages everything into a tarball, uploads it, and creates the automation

Request

curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/plugin" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Plugin Automation",
    "plugins": [
      {"source": "github:owner/repo", "ref": "v1.0.0"},
      {"source": "github:owner/another-plugin"}
    ],
    "prompt": "Use the plugin commands to perform the task",
    "trigger": {
      "type": "cron",
      "schedule": "0 9 * * 1",
      "timezone": "UTC"
    }
  }'

Request Fields

Plugin Source Formats

Response (HTTP 201)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "My Plugin Automation",
  "trigger": {"type": "cron", "schedule": "0 9 * * 1", "timezone": "UTC"},
  "enabled": true,
  "created_at": "2025-03-25T10:00:00Z"
}

Plugin Preset Examples

Single plugin with version:

curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/plugin" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Code Review Automation",
    "plugins": [
      {"source": "github:owner/code-review-plugin", "ref": "v2.0.0"}
    ],
    "prompt": "Review all Python files in the repository for code quality issues",
    "trigger": {"type": "cron", "schedule": "0 9 * * 1-5", "timezone": "UTC"}
  }'

Multiple plugins:

curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/plugin" \
  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Security Scan Automation",
    "plugins": [
      {"source": "github:owner/security-scanner"},
      {"source": "github:owner/report-generator", "ref": "main"}
    ],
    "prompt": "Run a security scan on the codebase and generate a report",
    "trigger": {"type": "cron", "schedule": "0 2 * * 0", "timezone": "UTC"},
    "timeout": 600
  }'

Monorepo plugin: ``