Outbound webhooks let Atoll notify external systems when work changes.
Use cases
- Notify a deployment system when an issue is marked done.
- Send task changes into a data warehouse.
- Trigger internal automation on assignment or priority changes.
- Mirror updates into Slack, Discord, or another project system.
Create a webhook
Or use the API:
The create response includes an Atoll-generated signing secret. Store it immediately; it is shown only once. This is distinct from the receiver-supplied Standard Webhooks whsec_ secret. Later list responses show only an origin-level destination_display, never URL paths, query credentials, or signing material.
Automation destinations use the same webhook resource. Set purpose to
automation (or both) and use auth: { "type": "bearer", "secret": "..." }
when the receiver requires Authorization: Bearer .... The token is stored in
the private versioned destination configuration and is never returned after a
write. Lists show only whether a Bearer token is configured.
An automation rule with the Issue assigned trigger also runs when a task is
created with an assignee. This includes recurring occurrences that inherit an
assignee. Use one assignment rule for creation, later assignment, and
reassignment; you do not need a second Issue created rule for the same
receiver.
Bearer secrets must contain only printable ASCII characters. Switching from none to Bearer requires a token and returns HTTP 400 if it is missing.
Set standard_webhooks.enabled to true with the receiver’s whsec_ secret to
also send Standard Webhooks headers. The secret is write-only and must be
canonical standard Base64 after whsec_, decoding to 24-64 bytes. Atoll signs
the exact raw body with webhook-id + "." + webhook-timestamp + "." + rawBody
using HMAC-SHA256 and sends webhook-signature: v1,<base64>, webhook-id, and
webhook-timestamp. The existing Atoll signature headers remain present. Every
outbound logical delivery also includes Idempotency-Key; automatic retries
keep the same value, while manual redelivery uses a new value. Each attempt
gets a fresh Standard timestamp and signature. A 2xx response proves receiver
acceptance only.
Receiver setup
Grok Automations supports this Standard Webhooks option. Configure the
Atoll destination as an automation destination with the whsec_ value from
Grok. Grok checks the three Standard headers and the five-minute timestamp
window; HTTP 202 means the event was accepted for processing, not that the
automation completed.
Hermes supports the same Standard Webhooks whsec_ verification on a
public HTTPS /webhooks/<route> endpoint. Configure the Hermes receiver
route/filter with events: ["automation.action"]; this is a Hermes receiver
setting. In Atoll, set the destination purpose to automation (or both)
and trigger it with an explicit send_webhook action; the Atoll destination
events field does not select automation actions. Hermes should allowlist and
render the v3 fields when present: data.project, data.issue,
data.automation.ruleId, data.automation.ruleName,
data.trigger.eventType, and data.trigger.changedFields. Issue payloads also
include the current persisted id, optional identifier and url, title,
status, priority, assigneeId, updatedAt, and an optional privacy-safe
artifacts count. CI payloads set data.issue to null and retain only the
useful ci fields, so handle CI events separately. Hermes can use webhook-id
for one-hour deduplication. A 2xx response is receiver acceptance, not proof of
agent completion. No live Hermes receiver test was run; this setup guidance is
based on source compatibility.
An automation rule references only the webhook UUID:
The action sends one automation.action payload through the existing delivery
queue. New automation deliveries use payload schema version 3. Retries
preserve the same delivery ID; a manual redelivery is a new logical delivery.
trigger.changedFields contains sorted public names from title, status,
priority, assigneeId, and projectId; raw before/after values are never
serialized. artifacts counts direct issue links in the same organization and
is omitted if that optional lookup fails, returns an invalid type, or cannot
complete within the bounded 1,000-row pagination limit. Projectless
issues use project: null and include the canonical organization issue URL when
available. CI events use issue: null, omit issue changes and artifact counts,
and retain ci.provider, repository, workflow, conclusion, branch, and
runUrl. Delivery identity stays in X-Atoll-Delivery-Id, webhook-id, and
Idempotency-Key; it is not repeated in the v3 body. Subscription broadcasts
and ping remain schema version 2. Existing queued payloads retain their
stored schema and content; manual replay preserves v3 body content and rewrites
a body deliveryId only for legacy v2 automation rows.
Atoll signs deliveries in the X-Atoll-Signature header as sha256=<hmac>, where the HMAC-SHA256 key is the SHA-256 hex digest of that secret and the message is the exact raw request body. X-Atoll-Signature-Version and X-Atoll-Signatures support bounded signing-key overlap. Each delivery also includes X-Atoll-Delivery-Id for receiver-side deduplication.
Automation action payloads use schema version 3 with current issue/project
enrichment and safe changed field names. Subscription broadcasts and ping
remain schema version 2. Both versions omit descriptions, comment bodies, raw
before/after values, and unrelated source data.
Update a destination
Use Edit in Webhook Settings, or PATCH /api/webhooks/{id}, to change its
URL, purpose, event subscriptions, enabled state, or authentication. Omitted
fields are preserved. For Bearer authentication, an omitted or blank secret
keeps the configured token; auth: { "type": "none" } clears it. Switching from
none to Bearer requires a token. URL and authentication changes create a new
private destination version. Previously queued deliveries retain the old version.
standard_webhooks is omitted from list responses except for its safe
configured boolean. Omit the object on update to preserve it, set
enabled: true with a blank secret to preserve an existing secret, provide a
new valid secret to replace it, or set enabled: false to clear it.
subscription receives matching broadcast events; an empty event list matches
all broadcast events. automation receives only explicit rule actions, regardless
of its event list. both permits both uses. All three purposes support a test ping.
Automation payload
A send_webhook action sends schema version 3 with
event: "automation.action". The top-level timestamp is the source event
time and orgId is the organization. The data object contains:
changedFields contains only title, status, priority, assigneeId, and
projectId; raw before/after values are omitted. Artifact counts cover direct
issue links in the same organization and the field is omitted when the optional
lookup fails, returns an invalid type, or cannot complete within the bounded
1,000-row pagination limit. Descriptions, comments, private
headers, credentials, raw audit metadata, and receiver response bodies are
excluded. Subscription broadcasts and ping remain schema version 2, and
existing queued payloads retain their stored schema and content. Automatic
retries keep the payload and delivery ID. Manual redelivery preserves v3 body
content and rewrites a body deliveryId only for legacy v2 automation payloads
that already contain it.
Inspect deliveries
Delivery history keeps safe outcome metadata, retry status, stable error_code, and next retry time. It does not return payloads, receiver response bodies, or raw errors. Atoll performs one 30-second request attempt per delivery invocation. Network failures and 5xx responses are recorded as retry_pending with next_retry_at; an internal drain retries due deliveries every 15 minutes.
Redeliver
Use redelivery after the receiving endpoint has been fixed.
Test
The test route sends a distinct ping event. It creates delivery evidence only, without an automation event, run, or action run.
Webhook URLs must use HTTPS DNS hostnames. IP literals, localhost, and .local hosts are rejected, private or otherwise non-public DNS results are blocked at delivery time, and redirects are not followed.
