Webhooks

Webhooks let ACP move from manual execution to event-driven operation. External systems can call into ACP to start threads, trigger project workflows, or connect runtime resources to the rest of your stack.

Trigger ACP work from external systems and real-world events.

Webhook quickstart

The fastest setup path is: create or pick the target computer, create a trigger, wire your external system to the returned webhook URL, then validate everything with the trigger test endpoint before sending live events.

Create trigger API Test trigger API Trigger executions API

1. Choose the ACP target for the webhook

Before creating the webhook itself, decide what environment the inbound event should run against. Every trigger must point at a computer via `environmentId`, and it can optionally lock execution to a specific agent with `agentId`.

Use one durable computer when webhook jobs should share files, packages, repos, or state across runs.

Add `agentId` when the event should always execute with one specific agent profile.

Keep one trigger per event boundary instead of one generic catch-all webhook for everything.

2. Create the trigger

Create the trigger first. ACP returns both a `webhookUrl` and a `webhookSecret`. In the ACP settings UI, you choose the source, event, computer, optional agent, and action. Use `Start thread` when the event should launch a new thread, or `Comment on pull request` when a GitHub PR event should result in a comment posted back to the PR.

Required fields are `name`, `environmentId`, `source`, `event`, and `action`.

GitHub triggers require a connected GitHub account before ACP can list repositories or authenticate PR comment actions.

Use the repository selector and branch filter to scope GitHub delivery before execution starts.

Use `filters` only when you want ACP to drop unmatched payloads before execution.

Set `enabled: false` while configuring external delivery, then enable after testing if you want a safer rollout.

Create a webhook trigger

Create a GitHub pull request comment trigger

3. Deliver signed events to ACP

Send your external event to the returned `webhookUrl`. ACP verifies signatures before executing anything. For generic `webhook` and `custom` sources, sign the raw request body with HMAC-SHA256 using the returned `webhookSecret` and send the digest in `X-Webhook-Signature`. Also include the logical event name in `X-Webhook-Event`. For GitHub webhooks, paste the ACP `webhookUrl` and `webhookSecret` directly into the repository webhook settings and let GitHub deliver signed payloads for you.

Generic/custom webhooks use `X-Webhook-Signature: sha256=<hex>` and `X-Webhook-Event`.

GitHub webhooks use `X-Hub-Signature-256` and ACP reads the GitHub event from `X-GitHub-Event`.

GitHub PR comment actions automatically reuse the connected GitHub auth for the owning user during execution.

Slack webhooks use Slack’s native `X-Slack-Signature` and `X-Slack-Request-Timestamp` scheme.

Send a generic webhook into ACP

Configure a GitHub repository webhook

4. Test, inspect, and operationalize

Use ACP’s trigger test endpoint before wiring the webhook into a live system. Once delivery is live, inspect execution history so every inbound event remains auditable through trigger executions and the threads created by those executions.

Use `POST /v1/triggers/{triggerId}/test` to validate the trigger with a sample payload.

Inspect `GET /v1/triggers/{triggerId}/executions` to see what fired and whether execution succeeded.

Treat webhooks as durable operational entry points, not blind fire-and-forget requests.

Test a trigger with a sample payload

List trigger executions