Remote Triggers in Claude Code

TLDR verdict: RemoteTrigger lets an external HTTP caller wake a suspended Claude Code session and hand it a JSON payload as the next user message. Pair it with CronCreate for scheduled runs and you have a small durable agent, free of a separate worker service.

This page covers the lifecycle of a trigger, the payload format, auth patterns, the cron tools that complement it, and realistic use cases with code.

What RemoteTrigger is

A RemoteTrigger is an HTTP endpoint that resumes a Claude Code session when called. You register the trigger from inside a session, the tool returns a URL and a shared secret, and any external service that can POST JSON can invoke it. The session suspends after registration; the next incoming POST wakes it up with the payload as context.

That is the whole idea. No separate queue, no dedicated worker process, no long-running daemon you manage yourself. The agent stays warm, waits for an event, and resumes when called.

Registering a trigger

Inside a session the agent calls the RemoteTrigger tool:

RemoteTrigger(
  name="nightly-review",
  description="Receives a POST from the CI system after each main-branch merge to run a review"
)

The tool returns:

• A URL like https://api.claude.ai/v1/triggers/abc123
• A shared secret the caller must include in the Authorization header
• The trigger ID for later listing or deletion

Copy the URL and secret to whichever external service will call them. Examples: a GitHub webhook, a Slack slash command backend, a Sentry alert destination, a Stripe event handler.

The JSON payload format

The POST body is passed verbatim to the agent as the next user message. There is no schema constraint, but keep it compact and avoid embedding entire files; let the agent read files from the repo instead.

A minimal payload:

{
  "event": "pull_request.opened",
  "repo": "acme/api",
  "pr_number": 482,
  "base_sha": "abc1234",
  "head_sha": "def5678"
}

The agent receives this as the turn input and decides what to do. In the example above, it might gh pr checkout 482, read the diff, and post a review.

For structured payloads, document the schema alongside the trigger prompt so future-you or a teammate can reproduce what the agent expects.

Authentication

Two patterns work well:

• Shared secret - the default. The tool returns a secret, the caller includes it in the Authorization: Bearer header. Rotate by deleting and re-registering the trigger.
• Signature verification - for platforms like GitHub or Stripe that already sign webhook bodies, verify the signature inside the agent prompt before doing any side effects. Pair with an IP allowlist if your platform publishes one.

Never expose a trigger URL publicly without auth. Unauthenticated triggers become a cheap DoS vector: each call burns tokens.

Cron tools

RemoteTrigger handles event-driven wakeups. CronCreate handles scheduled ones.

CronCreate(
  schedule="0 2 * * *",
  command="Review yesterday's merges to main and summarize risk in Slack",
  description="Nightly merge review at 2am"
)

The schedule uses standard five-field cron syntax. The command is a prompt, not a shell string; the agent interprets it with access to its usual tools. At the scheduled time, Claude wakes a session, runs the prompt, and exits.

To manage schedules:

• CronList() - returns every active schedule with ID, expression, and last-run timestamp.
• CronDelete(id) - removes a schedule by ID.
• The schedule persists across machine reboots because it runs inside the Claude daemon, not on system cron.

Use cases that fit remote triggers

• Nightly code review - CronCreate fires at 2am, the agent reads yesterdays commits, posts a summary to Slack.
• Weekly dependency PR - every Monday morning the agent runs pnpm outdated, picks the three safest upgrades, opens one PR per package.
• PagerDuty ack - Sentry fires a webhook on a new production error, RemoteTrigger wakes Claude, the agent reads the stack trace and drafts a fix PR.
• Slack slash command - a /claude command in the team channel posts to the trigger URL; the agent reads the command and responds in-thread.
• Stripe event handler - on a new subscription event, the agent logs the event to a spreadsheet and mails the founder.
• GitHub issue triage - every new issue fires a webhook; Claude labels it, assigns it, and drafts a reply suggesting reproduction steps.

None of these requires a separate worker service. All of them use the existing Claude Code session as the worker, which is the whole point.

Integrating with GitHub webhooks

GitHub webhooks POST JSON on every repo event. Point the webhook at your trigger URL:

1. Register the trigger inside a session and copy the URL.
2. In repo Settings to Webhooks, add the URL and a secret. Pick the events you care about: pull_request, issues, push.
3. In the trigger prompt, document the event shape so the agent knows how to route.
4. Test by triggering the event once and watching the session log.

GitHub signs the payload with the secret in the X-Hub-Signature-256 header. Verify it in the agent prompt before acting; an unverified webhook is an invitation for spoofed events.

Integrating with Slack

Slack Events API also uses webhooks. The catch is the challenge response: Slack requires your endpoint to echo back a verification token on the first call. Handle that in the agent prompt:

If the incoming body has a `challenge` field, respond with exactly that value.
Otherwise, treat the `event` field as the real payload.

For slash commands, Slack expects a 200 response within 3 seconds. Ack immediately, then use the response_url for the real reply. That two-step pattern lets the agent take as long as it needs without timing out the Slack UI.

Security considerations for public endpoints

Triggers sit on the public internet. Threats to handle:

• Replay attacks - include a timestamp in the payload and reject anything older than five minutes.
• Prompt injection - the payload becomes part of the agent prompt. A hostile body can try to redirect the agent. Validate fields against an allowlist before using them.
• Credential leak - if the shared secret ends up in a git commit or a Slack message, rotate it by deleting the trigger and creating a new one.
• Resource exhaustion - a trigger URL that processes unauthenticated calls burns tokens. Always require auth and rate-limit at the caller side when possible.

For high-stakes integrations (payment events, admin actions), add a second auth factor: the trigger fires, the agent posts a confirmation link to Slack, a human clicks to approve. That keeps a person in the loop without adding a worker service.

Error handling and retries

When a RemoteTrigger call fails (bad auth, malformed body, agent error), the HTTP response carries the failure code. The caller is responsible for retries.

Recommended retry policy for external callers:

1. On 4xx errors (auth, bad payload), do not retry. Fix the caller.
2. On 5xx errors or timeouts, retry with exponential backoff: 5 seconds, 30 seconds, 2 minutes, then drop.
3. After three failures, log and alert a human.

For cron schedules, Claude logs failed runs. Check CronList output periodically for schedules whose last run returned an error; a silently failing nightly job compounds over a week.

Cost and quota

Each trigger invocation is a regular Claude Code session. Token cost applies the same as an interactive session. A weekly review prompt that reads 20 files and writes a 400-word summary runs about 30 to 80 cents on Sonnet 4.

At scale, watch for:

• A misconfigured GitHub webhook that fires on every commit rather than every merge. 200 commits a day times 30 cents lands at 60 dollars a day.
• A cron schedule that retries on its own before the previous run finishes.
• A Slack bot whose users discover /claude and run it hundreds of times as a novelty.

Set a monthly budget alert in the Anthropic console. Most teams do not need more than 100 dollars a month of trigger-driven work, so set the alert at 200 and investigate if you hit it.

A complete example: weekly dependency PR

The full flow for a weekly dependency upgrade:

CronCreate(
  schedule="0 10 * * 1",
  command="Check pnpm outdated in /srv/app. Pick three non-major upgrades. For each, open a PR titled 'chore(deps): bump <pkg>'. Run tests on each PR branch. If tests pass, mark the PR ready for review. If they fail, close the PR with a comment explaining why.",
  description="Monday morning dependency sweep"
)

Once a week, Claude wakes up at 10am local, reads outdated packages, picks three safe ones, opens three PRs, runs tests, and marks the PRs. A human reviews and merges. Nothing to maintain, no worker to deploy.

That is the shape of most useful remote-triggered work: small, repeatable, well-scoped, and agentic.