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

# Webhooks

> Connect third-party systems to your agent with per-source endpoints, signature verification, and asynchronous delivery.

The webhooks channel lets external systems — a payments provider, a code host, an internal service — notify an agent when something happens, by calling a URL you control.

An agent can have **multiple webhook endpoints**, typically one per third-party source. Each endpoint has its own URL, its own verification method, and its own limits.

## Creating an endpoint

<Steps>
  <Step title="Name">
    Give the endpoint a name that identifies its source (for example, "Stripe — billing events").
  </Step>

  <Step title="Verification preset">
    Choose how incoming requests will be verified. See [Verification presets](#verification-presets) below.
  </Step>

  <Step title="Secret">
    Supply the secret used to verify incoming requests (for example, the signing secret from your provider's dashboard, or one you generate yourself — minimum 8 characters). It's encrypted at rest and never displayed again after creation.
  </Step>

  <Step title="Review">
    Confirm the configuration. The endpoint's URL is generated and shown **once** — copy it into the third-party system's webhook settings immediately, since it won't be displayed again.
  </Step>
</Steps>

<Warning>
  The endpoint URL is shown only at creation (and again after a rotation). If you lose it, you'll need to rotate the endpoint to get a new one — the old URL stops working immediately when you do.
</Warning>

## Verification presets

| Preset                | Signature header                                | Notes                                                                                                                        |
| --------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Stripe**            | `Stripe-Signature`                              | Verifies Stripe's own signature scheme with the secret from your Stripe dashboard                                            |
| **GitHub**            | `X-Hub-Signature-256`                           | Verifies GitHub's HMAC signature, configured in the repository's webhook settings                                            |
| **Standard Webhooks** | `webhook-signature`                             | Verifies the open [Standard Webhooks](https://www.standardwebhooks.com/) scheme, also used by several other providers        |
| **Shared secret**     | Configurable header, default `x-webhook-secret` | A static header value compared against your secret using a constant-time comparison                                          |
| **None**              | —                                               | No signature verification — the endpoint's secret URL is the only protection. Reserve this for trusted internal sources only |

<Tip>
  Pick the strongest preset your source actually supports. If it can sign requests (Stripe, GitHub, Standard Webhooks), use that — fall back to shared secret only when the source can't sign, and avoid **None** outside of trusted internal systems.
</Tip>

## Settings

Once created, an endpoint can be configured further:

* **Name** and **active/paused** status — pausing stops delivery without deleting the endpoint or its history
* **Event filters** — narrow which events actually reach the agent. Each filter checks a field (given as a JSON dot-path) against a value using an operator: `eq`, `neq`, `in`, `exists`, or `contains`. Multiple filters on the same endpoint are combined with **AND**. Events that don't match are recorded but never delivered to the agent
* **Overrides** — per-endpoint limits that default to the platform-wide values:

| Setting          | Default             |
| ---------------- | ------------------- |
| Rate limit       | 10 events/minute    |
| Daily quota      | 500 events/day      |
| Max payload size | 1 MiB (up to 5 MiB) |

<Note>
  On top of each endpoint's own quota, every agent has an **aggregate cap of 1,000 events/day across all of its webhook endpoints combined**.
</Note>

### Danger zone

* **Rotate token and/or secret** — two independent actions. Rotating the token generates a new URL (shown once) and invalidates the old one immediately, with no overlap window; rotating only the secret keeps the URL unchanged. Use this if a URL or secret may have leaked.
* **Delete** — removes the endpoint. Third-party sources still pointed at it will start receiving errors.

## Delivery to the agent

Webhook delivery is **asynchronous only** — the agent never sends a synchronous HTTP response back to the calling system. The endpoint simply acknowledges receipt; the agent processes the event on its own turn.

If several events arrive before the agent's next turn, they're **batched into a single digest** instead of triggering one turn per event — so a burst from a third party doesn't flood the agent.

Delivery is retried automatically so nothing gets stuck:

* immediately, if the agent is already connected
* when the agent reconnects
* at the end of the agent's current turn, if events arrived mid-turn
* on a periodic sweep, as a safety net for anything still undelivered

### Event log

Every event accepted by the pipeline — pending, delivered, filtered out (skipped), or quarantined — is recorded in the endpoint's event log, filterable by status. Permanently rejected calls (invalid signature, inactive endpoint, oversized payload) don't create log entries; they're counted in aggregate on the endpoint. From the log you can **resend an event to the agent** manually, which is useful after fixing a filter or reactivating a paused endpoint.

### What the agent sees

Only non-sensitive headers are captured and shown to the agent — headers like `Authorization` or `Cookie` are never stored, even if the source sends them. Payload content is presented to the agent as untrusted external input.

## Security best practices

* Prefer a signed preset (Stripe, GitHub, Standard Webhooks) over shared secret or none whenever the source supports it.
* Rotate secrets periodically, and immediately if you suspect a leak.
* Use event filters to keep the agent focused on events that actually matter, reducing noise and quota usage.
* Give each third-party source its own endpoint rather than sharing one — it keeps verification, filters, and quotas isolated per source.

## See also

* [Channels overview](/channels/overview) — principles shared across all channels
* [Email](/channels/email) — for unstructured, human-originated messages instead of system events
* [Activity](/guides/activity) — every delivered webhook event appears in the timeline tagged with the webhook badge