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
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.
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 asecret. 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.
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-onlydestination_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 asretry_pending and handled by the background retry drain.
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 immutableproject_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 creatorwebhook.manage(new webhook)andwebhook.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 projectsend_webhookaction separately requires the execution actor’s currentwebhook.dispatch(webhook)and matching rule, event, and destination projects. Project Admin alone grants no webhook permission to agents.
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.
- (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 nullableparent_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.
