Automations

An automation saves everything a session needs: a pinned agent version, an environment, an opening prompt, and run defaults such as credentials and files. Its triggers decide when it starts a session, and every start is recorded as a run, so you can see why each session began and what it was given. You can manage automations in the console, under Automations, or through the REST API with an API key. Both work on the same automations.

You need an agent version and an environment. Saving checks that both exist. Runs need the environment’s setup verified: a run on an unverified environment fails with environment_not_verified. See Agents and Verify the setup script. Slack and GitHub triggers also need an event source: connecting Slack or GitHub on Integrations creates one. See Receive events. Creating automations and starting runs by hand needs create permission, changing, pausing, and resuming them needs update, and deleting needs delete. Organization developers and admins have all of them. See Organizations and roles.

Create an automation

Choose the agent version, environment, and instructions, then add the triggers that should start runs.

Console
cURL

In the sidebar, click Automations, then click New automation. To start from a ready-made automation, click Start from a template at the top of the form and choose one; it fills in the name, triggers, and instructions, and you still choose the agent and environment.
Name it, choose the agent, its version, and an environment.
Under Instructions, write what the agent should do each time.
Add triggers: Scheduled, Slack, or GitHub. With none, the automation runs only with Run now.
Optionally set Credential access, Files, and, under Advanced, Run metadata.
Click Create automation. It starts paused.

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/automations' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Idempotency-Key: weekday-triage-2026-09-30' \
  -H 'Content-Type: application/json' \
  -d '{
    "displayName": "Weekday triage",
    "agentId": "5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55",
    "agentVersionId": "c1a94e07-2f6b-4d18-b3a5-0e7d8c6f4a21",
    "environmentId": "9d3e7b52-1a4c-4f80-b6e9-2c8a5d0f7e13",
    "initialPrompt": {
      "type": "literal",
      "text": "Read the issues opened in acme/api since the last weekday and post a triage summary."
    },
    "runDefaults": { "metadata": { "team": "platform" } },
    "triggers": [
      {
        "type": "schedule",
        "triggerId": "3f6a9c21-7d4e-4b85-a0c3-5e8d2f1b7a64",
        "enabled": true,
        "schedule": { "cron": "0 9 * * 1-5", "timezone": "Europe/London" }
      }
    ]
  }'

A 201 response is the full automation, with status paused and a revision. Some fields are left out here.

{
  "automationId": "a2d7e4c9-1b35-4f86-9e02-7c4b8d1f6a53",
  "displayName": "Weekday triage",
  "agentVersionId": "c1a94e07-2f6b-4d18-b3a5-0e7d8c6f4a21",
  "status": "paused",
  "revision": 1,
  "createdAt": "2026-09-30T09:12:04Z",
  "updatedAt": "2026-09-30T09:12:04Z"
}

The ETag response header is an opaque validator; send it unchanged as If-Match on the next change. Do not construct it from the body’s revision. New automations start paused: test one with Run now from its row’s Actions menu, then resume it so its triggers can start runs. See Run, pause, and resume.

Required fields

Every request field is required: displayName, agentId, agentVersionId, environmentId, initialPrompt, runDefaults (at least metadata, which can be null), and triggers (an empty list for manual runs only). You choose each triggerId yourself, as a UUID, and keep it stable across replacements.

Retries, Idempotency-Key, and If-Match

Operation	Needs	Retrying
`createAutomation`, `runAutomation`	`Idempotency-Key`	Resend the same request with the same key; it replays the first response instead of creating a second automation or run.
`replaceAutomation`, `deleteAutomation`, `pauseAutomation`, `resumeAutomation`	`If-Match` with the current returned `ETag`	Not safe to replay blindly. Read the automation again, then retry with its new `ETag`.
`pauseEventSource`, `resumeEventSource`	`If-Match` with the source’s current `ETag`	Read the source again, then retry.
Lists, reads, and status	Nothing extra	Safe to retry.

Copy the complete returned ETag, quotes included. A missing If-Match returns 428 precondition_required; a stale one returns 412 precondition_failed. A public contract change can invalidate an ETag even when the body’s revision is unchanged: read the resource again before retrying. See Idempotent mutations and Errors.

Choose triggers

An automation has up to 20 triggers, and a run starts when any enabled one matches. The trigger types are schedule, slack, github, and webhook. Turn a trigger off with enabled: false to keep it without it starting runs. You can also start a run by hand at any time, even while the automation is paused.

Schedule

Starts runs on a cron expression read in a time zone, such as the create example’s 0 9 * * 1-5 in Europe/London: 9:00 on weekdays. By default, an occurrence is skipped while the previous run’s session is still going.

Schedule fields

These fields go inside the trigger’s schedule object. Every one you save is applied to the schedule.

Field	Meaning
`cron`	A five-field cron expression, such as `0 9 * * 1-5` for 9:00 on weekdays. The console also offers Hourly, Daily, Weekdays, and Weekly.
`timezone`	The IANA time zone the expression is read in, such as `Europe/London`.
`overlapPolicy`	What happens when the previous run’s session is still going. See Overlap policies. The default is `skip`.
`catchupWindowSeconds`	How late a missed occurrence can still run, from 10 seconds to a year. The default is 900, 15 minutes.
`jitterSeconds`	Up to this many seconds of delay, from 0 to 540, so many schedules don’t all start on the same second. The default is 10; 0 turns it off.
`startAt`, `endAt`	Optional times the schedule starts and stops, inclusive. Before `startAt` and after `endAt`, the schedule starts no runs.

Overlap policies

`overlapPolicy`	Console label	Behavior
`skip`	Skip the next run	The occurrence is skipped.
`buffer_one`	Queue one run	One occurrence waits and runs when the previous finishes.
`buffer_all`	Queue every run	Every occurrence waits its turn.
`allow_all`	Run in parallel	Occurrences run at the same time.
`cancel_other`	Cancel the previous session	The running session is cancelled, and the new occurrence runs.

Check a schedule's status

The console shows each schedule’s next and last run, upcoming runs, and occurrences skipped for overlap or missed outside the catch-up window. It also shows whether each saved schedule is in effect. getAutomationStatus returns the same values for each schedule trigger:

curl 'https://api.recursion.labelbox.com/managed-agents/v1/automations/a2d7e4c9-1b35-4f86-9e02-7c4b8d1f6a53/status' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

{
  "automationId": "a2d7e4c9-1b35-4f86-9e02-7c4b8d1f6a53",
  "triggers": [
    {
      "triggerId": "3f6a9c21-7d4e-4b85-a0c3-5e8d2f1b7a64",
      "synchronization": "synced",
      "available": true,
      "paused": false,
      "nextRunAt": "2026-10-01T08:00:07Z",
      "lastRunAt": "2026-09-30T08:00:04Z",
      "upcomingRuns": ["2026-10-01T08:00:07Z", "2026-10-02T08:00:03Z"],
      "skippedOverlap": 0,
      "missedCatchupWindow": 0
    }
  ]
}

Slack

Starts a run for Slack messages. It needs a Slack event source: connect Slack on the Integrations page. Choose the message or app_mention event and the channels to accept. This trigger starts a run for each new top-level post in an incident channel that mentions a severity, and ignores other Slack apps:

{
  "type": "slack",
  "triggerId": "9c4f2e81-5a7d-4b36-8e19-2f6c3d0a7b58",
  "enabled": true,
  "eventSourceId": "d2b8f6a4-3e17-4c95-a0d6-8b1e5f9c2a73",
  "events": ["message"],
  "routing": { "workspaceIds": [], "channelIds": ["C0APQ7Z1K2M"] },
  "botEvents": { "mode": "ignore" },
  "filters": { "textContains": ["sev1", "sev2"], "ignoreThreadReplies": true }
}

Filter message triggers by text. Without a text filter, every new message in the trigger’s channels starts its own run and a paid session, with no cap. The editor warns about this but still saves. Add textContains or textMatches so only the messages you mean start work.
One post starts one run. Slack sends a message that mentions the app as both a message and an app_mention event. One post starts one run per automation, even when a trigger lists both events or two of its triggers each match.
Every Slack event starts a new session. A reply in the same thread starts another run with its own session; it doesn’t continue the earlier one.

Slack trigger fields

Field	Meaning
`eventSourceId`	The Slack source.
`events`	`message`, `app_mention`, or both. A post that matches both starts one run per automation.
`routing.channelIds`	Channels to accept. An empty list accepts every channel. The console picks channels the Slack app is a member of.
`routing.workspaceIds`	Workspaces to accept. An empty list accepts every workspace the source receives.
`botEvents.mode`	`ignore` to skip messages from other Slack apps, or `allow_external` to accept them. Messages from the source’s own app never start runs.
`allowSharedChannels`	`true` to accept channels shared with other organizations. The default is `false`.
`filters`	Optional `textContains`, `textExcludes`, `textMatches` (a regular expression), and `ignoreThreadReplies`. Text matching ignores case.

The console lists up to 1,000 channels the connected Slack app is a member of. Invite the app to a channel to make it selectable. The same list is available from the API for a Slack connection:

curl 'https://api.recursion.labelbox.com/managed-agents/v1/integrations/connections/b4e81f26-9c3d-4a57-8e10-2d6f5a9c7b43/channel-catalog' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

Messages that never start runs, and stopping a Slack session

Only newly posted messages start runs. Editing or deleting a message never starts one.
Direct messages to the app don’t start runs. Use a channel.
Stopping a Slack-started session posts nothing to its thread. The console reminds you when you force-stop or interrupt one. Reply in the thread yourself, or message the agent to post an update.

GitHub

Starts a run for GitHub webhook events. It needs a GitHub event source: connect GitHub on the Integrations page. This trigger matches pull_request deliveries in acme/api with the action opened or synchronize on fix/* branches, and ignores drafts and bots:

{
  "type": "github",
  "triggerId": "8b2e4d71-6c39-4a05-9f18-3d7a5c1e9b42",
  "enabled": true,
  "eventSourceId": "e1c7a3f9-4b26-4d80-a5e3-9f2b6d8c1a07",
  "events": ["pull_request"],
  "filters": {
    "repositories": ["acme/api"],
    "actions": ["opened", "synchronize"],
    "branches": ["fix/*"],
    "excludeDrafts": true,
    "ignoreBots": true
  }
}

The event only starts the run. To read or change the repository, the agent needs a GitHub grant, and it works through GitHub’s MCP tools. No GitHub credential is placed in the sandbox, so git and gh there aren’t authenticated. See GitHub access.

Three more common triggers. This one hands a pull request to the agent when someone adds the agent-ready label:

{
  "type": "github",
  "triggerId": "4a7c9e23-8d15-4f60-b2e8-6c1d3a5f9b07",
  "enabled": true,
  "eventSourceId": "e1c7a3f9-4b26-4d80-a5e3-9f2b6d8c1a07",
  "events": ["pull_request"],
  "filters": {
    "repositories": ["acme/api"],
    "actions": ["labeled"],
    "addedLabels": ["agent-ready"],
    "excludeDrafts": true,
    "ignoreBots": true
  }
}

This one starts a run when a pull request comment contains the command /agent fix:

{
  "type": "github",
  "triggerId": "b3e5d8f1-2c74-4a96-8d0b-5f7e1c9a3d62",
  "enabled": true,
  "eventSourceId": "e1c7a3f9-4b26-4d80-a5e3-9f2b6d8c1a07",
  "events": ["issue_comment"],
  "filters": {
    "repositories": ["acme/api"],
    "actions": ["created"],
    "commentOn": "pull_request",
    "textContains": ["/agent fix"],
    "ignoreBots": true
  }
}

This one starts a run when a CI workflow run on main finishes with a failure:

{
  "type": "github",
  "triggerId": "7f2a6c94-1e58-4d3b-a9c7-0b4e8d2f6a15",
  "enabled": true,
  "eventSourceId": "e1c7a3f9-4b26-4d80-a5e3-9f2b6d8c1a07",
  "events": ["workflow_run"],
  "filters": {
    "repositories": ["acme/api"],
    "actions": ["completed"],
    "conclusions": ["failure"],
    "branches": ["main"]
  }
}

GitHub trigger fields and filters

Field	Meaning
`eventSourceId`	The GitHub source.
`events`	GitHub event names. The console offers only the events that can start runs. A save that names any other event is refused, and the error lists the accepted names.
`filters`	Optional conditions, all of which must match.

Filter	Matches
`repositories`	Repository full names (`owner/name`), ignoring case. The console’s repository picker lists the repositories of the connection’s GitHub installation.
`actions`	Delivery actions, such as `opened`, `labeled`, `submitted`, or `completed`.
`branches`	Globs for the pushed branch, the workflow run’s head branch, or the pull request’s head branch.
`baseBranches`	Globs for the pull request’s base branch.
`labelsAny`, `labelsNone`, `addedLabels`	Labels on the pull request or issue, or the label just added.
`senders`, `ignoreBots`	The GitHub account that caused the delivery.
`excludeDrafts`, `merged`	Draft pull requests, and whether a closed pull request was merged.
`commentOn`	For `issue_comment`: `pull_request` or `issue`.
`reviewStates`, `conclusions`	Submitted review states, and completed workflow run conclusions.
`textContains`, `textExcludes`, `textMatches`	The comment or review body, or else the pull request or issue title and body, ignoring case. `textMatches` is a regular expression.

In globs, * matches any characters, including /, and ? matches one character.

Webhook

Starts a run for deliveries to a custom webhook source. The console offers this trigger when your organization has a custom source. Add filters.fieldEquals to start runs only for some deliveries. Each condition names a dot-separated path into the JSON body, such as data.level, and the value it must equal, written as JSON text without quotes.

{
  "type": "webhook",
  "triggerId": "5d9c1e37-2a84-4f60-b7c3-1e8a4d6f9b25",
  "enabled": true,
  "eventSourceId": "7a4e2c18-9d53-4b61-8f07-2c6e9a3d5b14",
  "filters": { "fieldEquals": [{ "path": "data.level", "value": "critical" }] }
}

To send deliveries to the source, see Send a custom webhook delivery.

Set run defaults

runDefaults applies to every run, whether a trigger or a person starts it.

Field	Meaning
`metadata`	String key/value pairs copied onto every session, for example to find them later. `null` for none. Their count and size limits are in Limits.
`vaultIds`	Vaults each session can use. Leave it out to use the agent’s default vaults. An empty list grants no vault access.
`credentialRefs`	Specific credentials within `vaultIds`. Leave it out to grant everything in those vaults.
`resources`	Files from your organization, each with a `fileId` and a `mountPath` under the session’s files directory, such as `/data/input.csv`.

Keep untrusted input in check

Event runs put outside text into the session: Slack messages, pull request and issue titles and bodies, comments, and webhook bodies. Treat that text as untrusted input. Someone who can post in the channel or open an issue can try to steer the agent.

Restricted environments drop web_fetch. A session an automation starts, or a session started from a Slack thread, gets no web_fetch tool when its environment limits internet access (limited or no access). The environment’s network policy is then its only way out.
Unrestricted environments keep web_fetch and full internet access. An injected instruction could ask the agent to send data anywhere. Use a limited environment for automations that read outside text, and grant only the credentials and repositories the task needs.
Webhook runs record only the sender’s headers. The event in a webhook run keeps the headers the sender sent. Headers added on the way to the event source are never recorded.

See Environments and Security.

Run, pause, and resume

Start one run by hand to test the automation, then resume it so its triggers can start runs.

Console
cURL

In Automations, open the automation row’s Actions menu.
Click Run now to start one run, or Run with input to add a JSON payload. Both need create permission.
Click Resume to let its triggers start runs, or Pause to stop them.

Set AUTOMATION_ETAG to the complete ETag header returned by the current automation read. Refresh it from each write response before the next change.

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/automations/a2d7e4c9-1b35-4f86-9e02-7c4b8d1f6a53/runs' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Idempotency-Key: triage-rerun-2026-09-30' \
  -H 'Content-Type: application/json' \
  -d '{"payload": {"repository": "acme/api", "since": "2026-09-29"}}'

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/automations/a2d7e4c9-1b35-4f86-9e02-7c4b8d1f6a53/resume' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H "If-Match: $AUTOMATION_ETAG"

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/automations/a2d7e4c9-1b35-4f86-9e02-7c4b8d1f6a53/pause' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H "If-Match: $AUTOMATION_ETAG"

runAutomation answers with the run. What success means: the run moves from pending to created, and sessionId names the session it started. Follow that session like any other; see Sessions. Resume returns the automation with status active. Pausing stops triggers from starting runs; Run now still works. Each change raises the revision, so use the new ETag for the next one.

Run input, failed runs, and automatic pauses

payload is optional and can be any JSON value up to 64 KiB (65,536 bytes) as JSON; a larger one is refused with 400 on payload.A run that couldn’t start a session ends failed with an error that has a code, a message, the field or resourceId responsible when there is one, and retryable.Resume is refused with 422 automation_reference_invalid while the automation’s agent, agent version, or environment is deleted; the automation stays paused. If a run fails because something the automation uses no longer exists, such as its agent, environment, a vault, a credential, or a file, the automation is paused, and the run’s error says what is gone. Fix the automation, then resume it.

See run history

In Automations, choose View runs from the automation row’s Actions menu. Each run shows its Trigger, when it started, and Session creation. Filter by status, trigger, or date, and click a run for its Run detail and a link to its session. In the API, list an automation’s runs, then read one. getAutomationRun returns one run with its frozen snapshots and effectiveInitialMessage.

curl 'https://api.recursion.labelbox.com/managed-agents/v1/automation-runs?automationId=a2d7e4c9-1b35-4f86-9e02-7c4b8d1f6a53&status=failed' \
  -H "Authorization: Bearer $RECURSION_API_KEY"
curl 'https://api.recursion.labelbox.com/managed-agents/v1/automation-runs/6e3b9d14-8a27-4c50-b1f9-0d5c7e2a4b86' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

{
  "automationRunId": "6e3b9d14-8a27-4c50-b1f9-0d5c7e2a4b86",
  "automationId": "a2d7e4c9-1b35-4f86-9e02-7c4b8d1f6a53",
  "triggerType": "manual",
  "status": "created",
  "sessionId": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
  "statusUrl": "/v1/automation-runs/6e3b9d14-8a27-4c50-b1f9-0d5c7e2a4b86",
  "createdAt": "2026-09-30T09:20:11Z",
  "updatedAt": "2026-09-30T09:20:13Z"
}

Run filters and paging

listAutomationRuns returns runs newest first. Filter with automationId, triggerId, eventSourceId, triggerType, status, createdAtGte, and createdAtLt, and page with limit and cursor.

Change or delete an automation

Saving a change keeps the automation’s current status. Deleting it removes its triggers while preserving records for runs that already started.

Console
cURL

In Automations, use the automation row’s Actions menu to open it for editing or to delete it. The automations list is newest first, and the editor shows the automation’s prompt and triggers. Click Save changes to save an edit.

listAutomations returns summaries, and getAutomation returns the full automation with its ETag. replaceAutomation takes the same complete body as create, so send every field you want to keep. Replace and delete need If-Match. Set AUTOMATION_ETAG to the current returned header and refresh it after a successful replace before deleting.

curl 'https://api.recursion.labelbox.com/managed-agents/v1/automations' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

curl -X PUT 'https://api.recursion.labelbox.com/managed-agents/v1/automations/a2d7e4c9-1b35-4f86-9e02-7c4b8d1f6a53' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H "If-Match: $AUTOMATION_ETAG" \
  -H 'Content-Type: application/json' \
  -d '{
    "displayName": "Weekday triage",
    "agentId": "5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55",
    "agentVersionId": "d8f25b1c-6e4a-4a93-b7c0-3f1e9d5a2c68",
    "environmentId": "9d3e7b52-1a4c-4f80-b6e9-2c8a5d0f7e13",
    "initialPrompt": { "type": "literal", "text": "Read the issues opened in acme/api since the last weekday and post a triage summary." },
    "runDefaults": { "metadata": { "team": "platform" } },
    "triggers": [
      {
        "type": "schedule",
        "triggerId": "3f6a9c21-7d4e-4b85-a0c3-5e8d2f1b7a64",
        "enabled": true,
        "schedule": { "cron": "0 9 * * 1-5", "timezone": "Europe/London" }
      }
    ]
  }'

curl -X DELETE 'https://api.recursion.labelbox.com/managed-agents/v1/automations/a2d7e4c9-1b35-4f86-9e02-7c4b8d1f6a53' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H "If-Match: $AUTOMATION_ETAG"

A delete answers 204.

If someone else saved first

If someone else saved the automation while you were editing it, Save changes saves nothing and shows This automation changed elsewhere. Nothing was saved. Choose Keep my edits to replace their version with yours on the next save, or Load the newer version to see what they saved.

Keep the agent version current

An automation keeps the agent version it was saved with. Later changes to the agent’s instructions, tools, and integrations don’t apply to its runs until you move it to the new version. In the Automations list, an Older version label marks automations that run an older version than their agent’s latest. When you open one, the drawer names both versions, for example “This automation runs Version 1 of backend-fixer. The agent is now on Version 2”, and offers Use Version 2. Click it, then Save changes. In the API, replace the automation with the new agentVersionId.

Receive events

An event source is an endpoint that receives events and checks they’re genuine. Automations listen to it through Slack, GitHub, and webhook triggers. One source can serve many automations, up to the enabled-trigger limit in Limits.

Source type (`type`)	Receives	Comes from
`slack_events_api`	Slack Events API callbacks.	Connecting Slack on Integrations.
`github_webhook`	GitHub webhook deliveries.	Connecting GitHub on Integrations.
`custom_webhook`	JSON from your own services.	Custom sources already in your organization.

Sources created by connecting an account are connection-managed: they start active, and you pause and resume them from the list.

Signing secrets and disconnecting

Slack and GitHub sources check every delivery against a signing secret that the connection creates and manages. Signing secrets never reach an agent sandbox. Disconnecting the account removes its source and stops its triggers. Existing automations keep those trigger settings so you can select a new source after reconnecting.

Manage sources

In Automations, open the Event sources tab. Each source’s health and last delivery are columns in the list, and its row’s Actions menu pauses or resumes deliveries. A healthy source has received a delivery, which does not prove the provider can reach it right now. A connection-managed source is changed and removed through its connection on Integrations. A custom source can be deleted when no automation uses it.

Source health

`health`	Meaning
`never_received`	No delivery has arrived yet.
`healthy`	A delivery has arrived.
`paused`	The source is paused.
`connection_unavailable`	The connection behind the source isn’t usable. Check or reconnect it on Integrations.
`setup_required`	The connected GitHub app needs its event permissions approved.

Manage sources with the API

listEventSources and getEventSource return sources, and getEventSourceStatus returns health, triggerCount, and lastDelivery. Pause and resume need If-Match with the source’s ETag. Set EVENT_SOURCE_ETAG to the complete header returned by getEventSource.

curl 'https://api.recursion.labelbox.com/managed-agents/v1/event-sources' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

curl 'https://api.recursion.labelbox.com/managed-agents/v1/event-sources/e1c7a3f9-4b26-4d80-a5e3-9f2b6d8c1a07/status' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/event-sources/e1c7a3f9-4b26-4d80-a5e3-9f2b6d8c1a07/pause' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H "If-Match: $EVENT_SOURCE_ETAG"

Send a custom webhook delivery

A custom source receives deliveries at its Callback URL, shown in Event sources. The full URL is the console’s address followed by the callback path, https://recursion.labelbox.com/agents/v1/event-sources/<eventSourceId>/events. Give it to the sender, and resume the source when you’re ready to receive events. Send a JSON body with POST to the callback URL. For an hmac_sha256 source, compute the HMAC-SHA256 of the exact body bytes, keyed with the source’s signing secret, and send it as lowercase hexadecimal in the signature header, after the prefix. Sign the bytes you send; re-serializing the JSON after signing breaks the signature.

POST /agents/v1/event-sources/7a4e2c18-9d53-4b61-8f07-2c6e9a3d5b14/events HTTP/1.1
Content-Type: application/json
X-Signature-256: sha256=5b1c9e0f3a7d2b8e4c6f1a9d3e7b2c5f8a0d4e6b9c1f3a5d7e2b8c4f6a0d9e1b

{"data":{"level":"critical","service":"billing"}}

A delivery that’s accepted returns 200 with {"ok": true}, and matching triggers on active automations start runs. The same signed body is treated as the same delivery, so a retry doesn’t start a second run. For an unsigned source, send an X-Webhook-Id or Idempotency-Key header to name the delivery.

Every delivery response

Response	Meaning
`200`	Accepted. Matching triggers on active automations start runs.
`401 unauthorized`	The signature didn’t match.
`400 invalid_request`	The body isn’t JSON, or the request is malformed.
`404 not_found`	The source doesn’t exist or was deleted.
`413 payload_too_large`	The body is over 1 MiB.
`429 rate_limited`	Too many deliveries. Retry after `Retry-After`.
`503 event_admission_unavailable`	The delivery couldn’t be recorded. Retry.

How automations run

Every run uses the pinned agent version. Publishing a new agent version doesn’t change the automation. See Keep the agent version current.
Everything is frozen per run. A run records the automation, trigger, and event exactly as they were, and the session’s opening message. Editing the automation later doesn’t change runs already started.
The opening message is your saved prompt. For an event run, it’s followed by Event for this run: and the event as JSON. For a manual run with input, it’s followed by Input for this run: and the input. For a scheduled run, it ends with This is a scheduled run for <time>., where the time is the occurrence in UTC, such as 2026-10-01T08:00:00Z.
Sessions show where they came from. A session an automation started shows Started by in its session panel: the automation, the trigger (Manual, Schedule, Slack, GitHub, or Webhook), and the run, each linked.

What can go wrong

The most common problems:

A run is failed. The session couldn’t start. Read the run’s error. If retryable is true, run it again; otherwise fix the named field or resource.
An automation paused on its own. A run found that something it uses was deleted. Read the failed run’s error, fix the automation, then resume it.
An event starts no runs. Check the source status and the trigger filters. A Slack message that was edited, deleted, or sent as a direct message never starts a run.
Runs still use access you removed from the agent. The automation runs its pinned agent version. Move it to the new version. See Keep the agent version current.

Every automation error

Code or symptom	Cause	Fix
`422 automation_reference_invalid` on save	The agent version or environment doesn’t exist or can’t be used.	Choose a live agent version and environment.
`422 automation_event_source_invalid`	A trigger’s event source is missing or is the wrong type for the trigger.	Use a Slack source for a Slack trigger, and so on.
`409 conflict` on `triggers`	The save would put an event source over its enabled-trigger limit. See Limits.	Switch off or delete triggers on that source, then save again.
A run is `failed` with `environment_not_verified`	The environment’s setup script hasn’t been verified, or the environment changed since it was. The automation stays active.	Run the environment’s setup; later runs then start. See Verify the setup script.
`422 automation_reference_invalid` on resume	The automation’s agent, agent version, or environment was deleted.	Choose a live agent version and environment, save, then resume.
An automation paused on its own	A run found that something it uses was deleted.	Read the failed run’s `error`, fix the automation, then resume it.
This automation changed elsewhere. Nothing was saved.	Someone saved the automation while you were editing.	Choose Keep my edits or Load the newer version, then save.
`428 precondition_required`	A replace, delete, pause, or resume sent no `If-Match`.	Read the resource and send its `ETag` as `If-Match`.
`412 precondition_failed`	The automation or source changed after you read it.	Read it again and retry with its new `ETag`.
`400` on `payload`	The run input is over 64 KiB as JSON.	Send less input, or put large data in a file.
`409 idempotency_conflict`	You reused an `Idempotency-Key` with a different request.	Use a new key for a new request.
A source can’t be deleted	Automations still use it, or it’s managed by its connection.	Remove it from their triggers first, or disconnect the account on Integrations.
A schedule never runs	The automation or trigger is paused or off, or the time is outside `startAt` and `endAt`.	Resume the automation, and check its schedule status.
A run is `failed`	The session couldn’t start.	Read the run’s `error`. If `retryable` is `true`, run it again; otherwise fix the named `field` or resource.
Runs still use access you removed from the agent	The automation runs its pinned agent version.	Move it to the new version. See Keep the agent version current.
No runs from a Slack message	The message was edited, deleted, or sent as a direct message, the channel isn’t routed, or the filters didn’t match.	Post a new message in a routed channel, and check the filters.
No runs from a GitHub or webhook event	The source is paused, the signature failed, or the filters didn’t match.	Check the source status and trigger filters.
The session has no `web_fetch`	The environment limits internet access, and the session was started by an automation or from Slack.	Allow the hosts the task needs in the environment’s network policy.
`health` is `setup_required`	The connected GitHub app needs its event permissions approved.	Approve the permission update in GitHub, then check the connection on Integrations.

For every error code, see Errors.

Limits

Limits on triggers, prompts, names, run input, run defaults, schedules, trigger filters, and custom webhook bodies are in Limits. Two more apply here:

A page of automations or event sources holds 1 to 100 items, 50 by default.
Name and prompt limits count UTF-8 bytes, not characters: an emoji or a non-Latin letter takes 2 to 4 bytes, so a name in those scripts fits fewer than 256 characters.

Next steps

Integrations

Connect Slack and GitHub to get event sources.

GitHub access

Give automated runs access to the repositories they work on.

Files

Mount the same files into every run.

Sessions

Follow the sessions automations start.

Get started

Account and access

Build agents

Coordinate multiple agents

Configure environments

Run and observe sessions

Manage agent context

Automate

Tutorials

Create an automation

Choose triggers

Schedule

Slack

GitHub

Webhook

Set run defaults

Keep untrusted input in check

Run, pause, and resume

See run history

Change or delete an automation

Keep the agent version current

Receive events

Manage sources

Send a custom webhook delivery

How automations run

What can go wrong

Limits

Next steps

Integrations

GitHub access

Files

Sessions

​Create an automation

​Choose triggers

​Schedule

​Slack

​GitHub

​Webhook

​Set run defaults

​Keep untrusted input in check

​Run, pause, and resume

​See run history

​Change or delete an automation

​Keep the agent version current

​Receive events

​Manage sources

​Send a custom webhook delivery

​How automations run

​What can go wrong

​Limits

​Next steps

Integrations

GitHub access

Files

Sessions

Create an automation

Choose triggers

Schedule

Slack

GitHub

Webhook

Set run defaults

Keep untrusted input in check

Run, pause, and resume

See run history

Change or delete an automation

Keep the agent version current

Receive events

Manage sources

Send a custom webhook delivery

How automations run

What can go wrong

Limits

Next steps