Automations and webhooks

AFK can start agent sessions from saved schedules or inbound webhooks. Use scheduled automations for recurring maintenance and webhooks for CI, monitoring alerts, GitHub Actions, or custom systems that should hand work to AFK without opening the browser.

How automations work

Automations store a reusable spawn configuration: project or repository, daemon, model, mode, isolation, resources, and a task template. A saved schedule fires on a time rule. A webhook fires when an external system POSTs to its authenticated endpoint. Both paths create normal AFK sessions that appear in the dashboard with the same chat history, visibility, and follow-up controls as browser-spawned sessions.

Creating a webhook

1. Open Account → Automations in the browser UI.
2. Click New webhook.
3. Give it a name (e.g. ci-fix-tests).
4. Configure the default spawn settings: local project directory and isolation, or a remote repository session with repo URL / GitHub App selection, daemon, model, mode, resources, and task template. Include{{body}} to embed the POST body, or use__AFK_BODY__ when you want a placeholder that is easier to place inside a fenced code block.
5. Copy the generated endpoint URL and token.

Scheduled automations

Use schedules for recurring work such as dependency audits, flaky-test sweeps, release note drafts, or weekly codebase health reports. AFK stores the schedule with the automation and starts a session when the timer fires. The dashboard includes month, week, and day calendar views backed by server-expanded occurrences for larger schedule sets, plus an upcoming agenda with paused schedules, schedule errors, latest-run health, and run-now controls so teams can see what is due without opening the full automation editor.

• Schedules use calendar-aware recurrence rules with an explicit time zone, so a “9:00 AM” automation follows local wall-clock time instead of drifting with UTC offsets.
• Timers are daemon-owned. If the selected daemon is offline, the run is skipped or delayed according to the automation's saved policy rather than running on an unexpected machine.
• Recurring runs use the saved spawn configuration, but you can still edit the automation before the next run to change model, mode, daemon, isolation, resources, or task template.
• Use Run now from the dashboard or Account → Automations to start an enabled schedule immediately using the same billing, concurrency, and run-log safeguards as a timed fire.

Managing automations

Account → Automations is the full management surface. Use the All, Scheduled, and Webhooks filters to narrow the list, inspect latest-run status badges, open recent sessions, retry eligible failed runs, and filter each run log by success, failed, skipped, or running status.

Endpoint URL

Webhook URLs have the format:

POST https://afk.mooglest.com/webhooks/{ownerId}/{webhookId}

The ownerId segment is a stable UUID-like identifier for your account or org — it avoids name clashes across accounts without exposing auth identifiers.

A legacy path /webhooks/{webhookId} is also supported for backwards compatibility.

Authentication

Provide the webhook token in any of these ways:

Authorization header

curl -X POST https://afk.mooglest.com/webhooks/{ownerId}/{id} \
  -H "Authorization: Bearer afk_webhook_token_here" \
  -H "Idempotency-Key: unique-event-id" \
  -H "Content-Type: application/json" \
  -d '{"task": "Run the test suite and fix any failures"}'

Custom header

curl -X POST https://afk.mooglest.com/webhooks/{ownerId}/{id} \
  -H "X-AFK-Token: afk_webhook_token_here" \
  -d '{"task": "Deploy the latest build to staging"}'

Query parameter

curl -X POST "https://afk.mooglest.com/webhooks/{ownerId}/{id}?token=afk_webhook_token_here" \
  -d '{"task": "Check for security vulnerabilities"}'

The query parameter method is useful for webhook providers that cannot set custom headers (e.g. some SaaS notification services).

Retry protection

To prevent a retried delivery from starting a duplicate session, send a stable event identifier in the Idempotency-Key header. Reuse the same value when retrying the same event and use a new value for each new event. AFK also recognizes X-GitHub-Delivery, X-Gitlab-Event-UUID, and X-Stripe-Event-Id. This header is recommended but optional; requests without one are still accepted, but AFK cannot identify later retries as duplicates.

Request body

The POST body is optional JSON. Supported fields:

Response

A successful POST returns HTTP 202 with the spawned session ID and run ID:

{
  "session_id": "abc123def",
  "run_id": "run456"
}

On auth failure: 401 Unauthorized
On entitlement limit: 402 Payment Required (inbound webhooks require an active trial, Max, Business, or Enterprise entitlement; see Billing and limits)
On invalid webhook ID: 404 Not Found

Google Chat

The recommended company setup is the AFK app for Google Chat. Install it from Google Workspace Marketplace, open a direct message with AFK, and select Continue with AFK. Each person first chooses their personal account or one of their active organizations, then connects their Google Chat identity to one existing enabled on-demand Automation in that scope. Scheduled Automations are not offered for chat connections. AFK selects the on-demand Automation automatically when there is only one in the chosen scope, asks the user when there are several, and links to AFK's Automations screen when none exist. Google Chat never creates or edits Automations. Different users in direct messages or shared spaces may choose different personal or organization Automations.

Mention AFK or use afk <task> in a shared space. In a direct message, plain text also works. Account → Integrations provides an Add to Google Chat action for the Marketplace installation. Message history requires a separate, one-time authorization by a Google Workspace administrator. The same screen shows the authorization status, links directly to the Google Admin Console's Configured apps page, and lets you retry the access check. The administrator must trust the OAuth scope https://www.googleapis.com/auth/chat.app.messages.readonly for AFK. Once approved, a new session can also receive recent public messages from the exact Google Chat thread and use conversation tools to read or search its originating thread or space. Reply delivery does not depend on this optional history permission, so AFK can still send an explicit reply to the originating thread when history access is unavailable. These tools never access other spaces, treat retrieved content as untrusted, and search only a bounded set of recent messages. If that permission is unavailable, AFK still runs the request without prior context or conversation tools. AFK keeps follow-ups in the same Google Chat thread attached to the same durable AFK session. Work and detailed responses remain private in AFK unless the agent explicitly publishes a message to the originating Google Chat thread; ordinary final responses are not sent automatically. Supported commands are new, status, connect, stop, and help.

Workspace administrators configuring a private test deployment should use the stable interaction endpoint POST /api/integrations/google-chat/eventsand set its exact public URL as the authentication audience. AFK verifies Google-signed requests and acknowledges them immediately while agent work continues asynchronously.

The older tokenized /google-chat/... webhook adapter remains available only for advanced private automation compatibility. It is not the Marketplace installation flow.

AFK for Slack

AFK for Slack brings the same guided account-linking and Automation experience to Slack. An administrator chooses Add to Slack, completes OAuth, and returns directly to AFK in Slack to connect their own AFK account and choose an Automation. Every other person gets the same guided action the first time they open the App Home, send a direct message, or mention AFK in a channel.

1. Create a Slack app and add bot scopes app_mentions:read, chat:write, im:history, channels:history, groups:history, channels:read, groups:read, and users:read. Reinstall the app after adding scopes so Slack grants them.
2. Subscribe the app to app_mention, message.im, app_home_opened, app_uninstalled, and tokens_revoked events.
3. Set the Events API request URL to your AFK server's /api/integrations/slack/events endpoint and the OAuth redirect URL to /api/integrations/slack/oauth/callback.
4. Configure AFK_SLACK_CLIENT_ID, AFK_SLACK_CLIENT_SECRET, AFK_SLACK_SIGNING_SECRET, AFK_SLACK_APP_ID, AFK_SLACK_REDIRECT_URI, and AFK_SECRETS_KEY.
5. In AFK, open Account → Integrations and choose Add to Slack.

Mention AFK in a channel or send the app a direct message. The App Home shows connection status, the selected Automation, example prompts, and a link to open AFK. First-time and repair flows use native Slack Block Kit messages instead of raw setup links. AFK preserves the initiating request, acknowledges it quickly, and keeps thread follow-ups attached to the same AFK session. Work and detailed responses remain private in AFK unless the agent explicitly publishes a message to the originating Slack thread; ordinary final responses are not posted automatically. Slack-created sessions can also read or search bounded recent history from that thread or its originating channel; they cannot access another channel, and all retrieved content is treated as untrusted. Slack may apply strict history API rate limits, so these tools use bounded requests and can ask you to retry later. AFK stores inbound events and completed replies until they are accepted for delivery. Account → Integrations shows Slack delivery health; administrators can inspect a failed delivery and chooseTry again after correcting runner, credential, or Slack API problems. Direct OAuth installation is the current rollout channel while Slack Marketplace review remains a release gate, not a separate product experience.

AFK for Discord

AFK for Discord is a guild-installed bot that listens for explicit mentions through the Discord Gateway and uses the existing AFK account-linking flow. An administrator chooses Add to Discord, installs the bot in a server, and users connect their AFK account and select an enabled on-demand Automation the first time they mention @AFK. Direct messages are not supported.

1. Create a Discord application and add a bot.
2. In the Discord Developer Portal, open the bot settings and enable the privileged Message Content Intent. AFK needs it to read the task text that follows an explicit mention.
3. Configure AFK_DISCORD_APPLICATION_ID, AFK_DISCORD_BOT_TOKEN, AFK_DISCORD_CLIENT_ID, AFK_DISCORD_CLIENT_SECRET, and AFK_DISCORD_REDIRECT_URI.
4. Request only View Channels, Send Messages, Read Message History, Send Messages in Threads, and Embed Links. Administrator permission is not required.

Mention @AFK with a task in a guild channel or Discord thread. If your Discord identity is not linked yet, AFK replies with the guided account-linking and Automation-selection flow; mention it again after linking. AFK suppresses generated mentions, keeps the originating channel or thread attached to one durable AFK session, and exposes bounded history only from that originating Discord conversation. Agent replies remain explicit through chat_reply; ordinary AFK final responses stay private.

The Gateway connection has a single active owner. Run one AFK server replica for a Discord-enabled deployment; multi-replica Gateway ownership and failover are not yet supported.

Run log

Every webhook invocation is recorded in the unified automation run log, accessible from the automation's management card and workspace dashboard. Failed runs include authentication failures, entitlement failures, and spawn failures.

Remote repositories and GitHub App installs

Webhooks can spawn either local host sessions or Docker-backed remote repository sessions. For GitHub repositories, connect the AFK GitHub App from Account → Git so the remote session form can browse accessible repositories and use short-lived installation tokens instead of long-lived personal clone tokens.

Use cases

GitHub Actions — auto-fix CI failures

# .github/workflows/fix-on-fail.yml
on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

jobs:
  auto-fix:
    if: github.event.workflow_run.conclusion == 'failure'
    runs-on: ubuntu-latest
    steps:
      - name: Trigger AFK to fix failures
        run: |
          curl -X POST "$AFK_WEBHOOK_URL" \
            -H "Authorization: Bearer $AFK_WEBHOOK_TOKEN" \
            -H "Content-Type: application/json" \
            -d '{"task":"The CI pipeline just failed. Investigate and fix the failures."}'
        env:
          AFK_WEBHOOK_URL: ${{ secrets.AFK_WEBHOOK_URL }}
          AFK_WEBHOOK_TOKEN: ${{ secrets.AFK_WEBHOOK_TOKEN }}

Monitoring alert — investigate an error spike

# Called by your monitoring system (Datadog, Grafana, etc.)
curl -X POST "$AFK_WEBHOOK_URL" \
  -H "X-AFK-Token: $AFK_WEBHOOK_TOKEN" \
  -d '{
    "task": "Error rate on /api/auth spiked to 15% at 14:32 UTC. Investigate the logs and identify the root cause.",
    "mode": "yolo"
  }'

Nightly maintenance

Prefer a saved schedule in Account → Automations for recurring maintenance. Use a cron job only when the trigger must live in another scheduler:

# External cron job or scheduled task
0 3 * * * curl -X POST "$AFK_WEBHOOK_URL" \
  -H "Authorization: Bearer $AFK_WEBHOOK_TOKEN" \
  -d '{"task":"Run the dependency audit. Update any packages with critical CVEs."}'

Org webhooks

When in org context, webhooks belong to the org (not a personal user). Org admins can manage org automations and webhooks in Account → Automations while in org context. Sessions spawned by org webhooks are scoped to the org and visible to org members according to normal visibility rules.