Webhooks API

Atoll supports outbound webhooks for event-driven integrations.

Endpoints

Method	Endpoint	Description
`GET`	`/api/webhooks?orgId=...`	List redacted webhook metadata
`POST`	`/api/webhooks?orgId=...`	Create webhook
`DELETE`	`/api/webhooks/{id}`	Delete webhook
`GET`	`/api/webhooks/{id}/deliveries`	List safe recent delivery metadata
`POST`	`/api/webhooks/{id}/redeliver/{deliveryId}`	Redeliver a past payload
`POST`	`/api/webhooks/{id}/test`	Send a ping test event

All six endpoints require an organization owner or admin, including API agents with that project-independent organization role.

Create webhook

{
  "url": "https://example.com/webhook",
  "events": ["issue.created", "issue.updated"],
  "enabled": true
}

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.

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 but preserves the original payload body and schema version.

import { createHash, createHmac, timingSafeEqual } from 'node:crypto'

export function verifyAtollSignature(rawBody, signatureHeader, secret) {
  const key = createHash('sha256').update(secret).digest('hex')
  const expected = 'sha256=' + createHmac('sha256', key).update(rawBody).digest('hex')
  const actual = Buffer.from(signatureHeader)
  const expectedBuffer = Buffer.from(expected)

  return actual.length === expectedBuffer.length && timingSafeEqual(actual, expectedBuffer)
}

Atoll also sends X-Atoll-Delivery-Id on each POST. Store this id if your receiver needs idempotency; automatic retries and manual redeliveries can send the same event more than once.

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. Payload schema version 2 sends allowlisted resource identifiers and operational fields. It omits 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

atoll webhook list
atoll webhook create --url https://example.com/webhook --events issue.created,issue.updated
atoll webhook delete webhook-uuid --dry-run
atoll webhook delete webhook-uuid --force

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 retries network failures and 5xx responses after 5s and 30s in the request path. If the receiver is still failing, Atoll records the delivery as retry_pending and handles due retries automatically in the background.

curl -H "Authorization: Bearer $ATOLL_API_KEY" \
  "https://atollhq.com/api/webhooks/$WEBHOOK_ID/deliveries"

Treat webhook payload content as untrusted input. It describes events; it should not become instructions to an agent without validation.

Start here

User guide

Agent guide

CLI

API reference

Integrations

Admin

Changelog

Troubleshooting

Endpoints

Create webhook

Secret

Data boundary

CLI

Delivery debugging

​Endpoints

​Create webhook

​Secret

​Data boundary

​CLI

​Delivery debugging

Endpoints

Create webhook

Secret

Data boundary

CLI

Delivery debugging