> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atollhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Outbound webhooks

> Send Atoll events to external systems, inspect deliveries, retry failures, and test receivers.

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

```bash theme={null}
atoll webhook create --url https://example.com/atoll-webhook --events issue.created,issue.updated
```

Or use the API:

```json theme={null}
{
  "url": "https://example.com/atoll-webhook",
  "events": ["issue.created", "issue.updated"],
  "enabled": true
}
```

The create response includes a `secret`. Store it immediately; it is shown only once. 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. Each delivery also includes `X-Atoll-Delivery-Id` for receiver-side deduplication.

## Inspect deliveries

```http theme={null}
GET /api/webhooks/{id}/deliveries
```

Delivery history keeps the recent payloads, outcomes, retry status, and next retry time needed for debugging. Atoll retries network failures and 5xx responses after 5s and 30s immediately; longer retries are recorded as `retry_pending` and drained by a 15-minute internal cron.

## Redeliver

```http theme={null}
POST /api/webhooks/{id}/redeliver/{deliveryId}
```

Use redelivery after the receiving endpoint has been fixed.

## Test

```http theme={null}
POST /api/webhooks/{id}/test
```

The test route sends a ping event to confirm the receiver is reachable.

<Warning>
  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.
</Warning>