Skip to main content
Atoll supports outbound webhooks for event-driven integrations.

Endpoints

Organization-owned destinations require the existing organization webhook administration authority. Project-owned destinations use project read access and the independent Create, Manage and Dispatch permissions described below. Project archive and restore publish project.archived and project.restored subscription events with the project ID and current status. They do not publish individual task archive events for inherited archive. Individual and bulk task archive publish the normal issue.updated event with archived_at in changedFields, while keeping the task’s workflow status. Archive Activity and durable webhook delivery are committed together; receivers must retain their normal delivery deduplication.

Create webhook

Use purpose: "automation" or "both" for a destination referenced by an automation rule. Bearer authentication accepts auth: { "type": "bearer", "secret": "..." }. The secret is write-only: responses expose only auth.type and auth.configured, never the token. The optional standard_webhooks object enables Standard Webhooks compatibility headers. Its receiver-supplied whsec_ secret is write-only and must be canonical standard Base64 after the prefix, decoding to 24-64 bytes. Atoll signs webhook-id + "." + webhook-timestamp + "." + rawBody with HMAC-SHA256 and sends webhook-id, webhook-timestamp, and webhook-signature: v1,<base64> alongside the existing Atoll headers. List responses expose only standard_webhooks.configured. The V1 automation action is { "type": "send_webhook", "webhook_id": "..." }. It targets one same-organization enabled destination and uses the existing delivery queue. New automation.action deliveries use payload schema version 3; delivery retries keep the same delivery ID.
The v3 project and issue fields come from the current tenant-scoped rows. Projectless issues use project: null and include a canonical organization issue URL when available. trigger.changedFields is a sorted list of safe public names (title, status, priority, assigneeId, projectId); raw before/after values are omitted. artifacts counts direct issue links in the same organization and is omitted when its optional lookup fails, returns an invalid type, or cannot complete within the bounded 1,000-row pagination limit. CI actions set issue: null, omit issue changes and artifacts, and retain ci.provider, repository, workflow, conclusion, branch, and runUrl. Delivery identity stays in headers and is not repeated in the v3 body. Subscription broadcasts and ping remain schema version 2. Webhook URLs must use HTTPS DNS hostnames. IP literals, localhost, and .local hosts are rejected at creation. Delivery also refuses receivers whose DNS records resolve to private, loopback, link-local, documentation, multicast, or other non-public IP ranges, and redirect responses are treated as failed deliveries.

Update webhook

PATCH /api/webhooks/{id} accepts any of url, events, enabled, purpose, auth, and standard_webhooks. Omitted fields are preserved. Omit or leave the Bearer secret blank to keep the configured token; select auth: { "type": "none" } to clear it. A URL, token, or Standard secret change creates a private version. For Standard Webhooks, omit the object to preserve it, use enabled: true with a blank secret to preserve an existing secret, provide a valid nonblank secret to replace it, or use enabled: false to clear it. Queued deliveries keep their pinned URL and authentication. Returns { webhook } with safe metadata only.

Secret

The create response includes a secret. Store it immediately; it is shown only once. Atoll sends an X-Atoll-Signature header with a sha256= prefix. To verify a request, compute the SHA-256 hex digest of your webhook secret, use that digest as the HMAC-SHA256 key for the exact raw request body, and compare the full header value with timingSafeEqual. During a bounded signing-key overlap, X-Atoll-Signature-Version identifies the primary key and X-Atoll-Signatures carries versioned signatures. Continue accepting the primary X-Atoll-Signature header for compatibility. Each logical delivery pins its primary signing version first, followed by overlap versions. Automatic retries preserve that ordering even after a new key becomes primary. Manual redelivery uses current active signing configuration and preserves the source event and schema version. Only legacy schema v2 automation.action payloads that already contain data.deliveryId get that body field rewritten during manual replay; v3 body content is preserved.
Atoll also sends X-Atoll-Delivery-Id and Idempotency-Key on each POST. Both values identify the logical delivery: automatic retries preserve them, while manual redelivery uses new values. Standard Webhooks receivers should verify the exact raw body and use the timestamped signing string described above. A 2xx response proves acceptance only.

Data boundary

List responses expose an origin-only destination_display, such as https://example.com/…. The deprecated url compatibility field contains the same redacted value. Paths, queries, fragments, and signing material are never listed. Automation action payloads use schema version 3 with current issue/project enrichment, safe changed field names, and optional artifact counts. Subscription broadcasts and ping remain schema version 2. Both versions omit issue descriptions, comment bodies, raw before/after values, and unrelated source fields. Delivery history similarly omits payloads, receiver response bodies, and raw errors; use status, status_code, error_code, and next_retry_at for diagnostics.

CLI

Delivery debugging

Use delivery history to inspect stable failure codes, retry status, and the next scheduled retry time, then redeliver after fixing the receiver. Atoll makes one 30-second request attempt per invocation. Network failures and 5xx responses are recorded as retry_pending and handled by the background retry drain.
Treat webhook payload content as untrusted input. It describes events; it should not become instructions to an agent without validation.

Vercel deployment callback

POST /api/webhooks/vercel/{connectionId} is an inbound provider callback, separate from Atoll outbound webhooks. Atoll selects one enabled connection by opaque UUID, bounds the raw body to 256 KiB, and verifies the x-vercel-signature HMAC-SHA1 before JSON parsing. It then checks the signed team/project/deployment IDs against authenticated Vercel deployment and project GET responses. No raw payload, credential, provider error body, or log is saved. Supported events are deployment.created, deployment.ready, deployment.succeeded, deployment.error, deployment.canceled, and deployment.promoted. A signed unsupported event returns 200 { "skipped": true }. A durably recorded event returns 200 { "accepted": true, "duplicate": false, "complete": true, "code": null }. A replay can return duplicate=true while still applying a newer authenticated environment/production snapshot. complete=false with a safe code means the observation is durable but identity or current production evidence is incomplete. Errors return { "error": "safe_code" }. Atoll never returns a successful acceptance before the atomic observation/reference/link projection commits. Vercel retry behavior is defined by its webhook API. Use owner reconciliation for bounded recovery after a delivery or configuration problem.

Project-owned webhook destinations

A project destination has an immutable project_id, purpose: "automation", and events: []. It receives targeted automation actions and explicit pings; it never subscribes to organization broadcasts. Agents need project read access and separate grants:
  • webhook.create(project) creates a destination. The same transaction grants its creator webhook.manage(new webhook) and webhook.dispatch(new webhook) and increments the agent permission revision. It grants no authority over another destination. A human can revoke these grants independently.
  • webhook.manage(webhook) permits edits, disable/delete, write-only credential rotation, explicit ping, redacted history, and proven same-project redelivery.
  • automation.manage(project) or existing project Admin access permits rule management. A project send_webhook action separately requires the execution actor’s current webhook.dispatch(webhook) and matching rule, event, and destination projects. Project Admin alone grants no webhook permission to agents.
Human project administrators can manage their project’s destinations. Current project access, enabled agent lifecycle, and unarchived project state are checked again in the durable write and delivery paths. Dispatch revocation blocks new and queued automation attempts; Manage revocation blocks later pings and manual replay. An attempt already authorized before a concurrent revocation can finish. Existing pinned credentials and logical retry identity remain unchanged. A disabled or deleted destination cannot accept a new attempt. Organization-owned destinations keep their existing administration and delivery behavior; omitting project context never grants a project agent organization access. Use GET /api/webhooks?orgId=ORG&projectId=PROJECT for redacted project metadata. The response includes can_create; each row includes can_manage and can_dispatch. POST includes project_id in the body. Item operations use the saved owner; optional ?projectId=PROJECT additionally checks the expected owner. Changing or clearing project_id, adding subscriptions, or using another project’s destination is rejected. Hidden scopes return 404, missing grants 403, invalid configurations 400, and archived or changed scopes 409. Bearer and receiver-supplied Standard Webhooks secrets are write-only. Omit them on update to preserve them. Later reads expose only configuration booleans and origin-level URL display. The generated Atoll signing secret is returned once on create, including through typed MCP. Store it securely; normal tool output may remain in conversation history. Rule dry-run sends nothing; Test webhook sends a distinct ping. History excludes payloads, responses, raw errors and secrets.
Secret files or - (stdin) keep credentials out of command arguments. Supply only one secret through stdin per call. Both MCP profiles expose atoll_list_webhooks, atoll_create_webhook, atoll_update_webhook, atoll_test_webhook, atoll_list_webhook_deliveries, atoll_redeliver_webhook, and atoll_delete_webhook, with optional explicit project_id. API authorization remains authoritative; agent permission administration remains human-only.

Hierarchy and parent readiness

Issue subscription payloads carry nullable parent_id and sub_issues_rollup with total and done. The new issue.ready_to_close subscription event records a transition to all active children done while the parent is open, including the ready transition before an authorized automatic close. Delivery is queued transactionally. Readiness does not itself grant permission to close a parent. Deduplicate delivery IDs with the existing signature/retry contract. See sub-issue close rules. Automation schema v3 issue objects also carry parent_id and sub_issues_rollup. These fields include only hierarchy readable by the rule actor; project-owned destinations further restrict hierarchy to their own project. Manual redelivery retains the original snapshot instead of recomputing hierarchy.