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

# Webhooks

> Receive AGO events such as new tickets or knowledge gaps on your own HTTPS endpoint, from the admin page or the API

A webhook sends AGO events to your HTTPS endpoint as they happen, such as a ticket created or reprioritized, a conversation handed to a human, or a knowledge gap detected. Your system can react without asking AGO for changes.

You can create a webhook three ways:

* In **Developer** > **Webhooks**, without code.
* With the REST API, from a script or an integration platform.
* From an MCP client, with `events/subscribe`. See [MCP Events](https://ago.mintlify.site/api/mcp-events.md#receive-events-by-webhook).

All three deliver the same signed messages, described in [Receive deliveries](#receive-deliveries).

## Manage webhooks in AGO

Open **Developer** > **Webhooks** to see every webhook of your workspace, whether it was created on this page, through the API or by an MCP client. Each row shows the event, its filters, the endpoint, who created it and its status:

* **Active**: deliveries succeed.
* **Failing**: the endpoint fails. AGO retries the same event and holds the following ones.
* **Suspended**: deliveries stopped after an hour of failures.

To add one, click **Add webhook**, choose an event, set **Only when** filters if you only need some cases (for example, `priority` = `Urgent`), and enter the endpoint URL. AGO checks the endpoint before saving (see [Verify the endpoint](#verify-the-endpoint)). Then the webhook page shows its **signing secret** once: copy it into your endpoint's configuration, as AGO cannot show it again. A webhook created here does not expire.

Click a webhook to see its status, the last error and the delivery history of the last 7 days. **Resume deliveries** restarts a suspended webhook from the event that failed. **Delete webhook** stops deliveries.

## Manage webhooks with the API

Use an API key created in **Developer** > **API Keys**, or an OAuth token. A key sees and manages only the webhooks it created. To subscribe to an event, the key needs that event's read scope, listed in the [event table](https://ago.mintlify.site/api/mcp-events.md#events), such as `tickets:read` for ticket events.

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/v1/event-subscriptions/events` | The events your key can subscribe to, with their filters and data fields |
| `GET` | `/api/v1/event-subscriptions` | Your webhooks, newest first (`page`, `page_size`) |
| `POST` | `/api/v1/event-subscriptions` | Create a webhook, or refresh it if it exists |
| `GET` | `/api/v1/event-subscriptions/{id}` | One webhook and its status |
| `DELETE` | `/api/v1/event-subscriptions/{id}` | Delete a webhook |
| `POST` | `/api/v1/event-subscriptions/{id}/resume` | Restart a suspended webhook from the event that failed |
| `GET` | `/api/v1/event-subscriptions/{id}/deliveries` | Delivery attempts of the last 7 days (`limit`, at most 100) |

### Create a webhook

```bash theme={null}
curl -X POST "https://your-workspace.api.useago.com/api/v1/event-subscriptions" \
  -H "X-API-Key: $AGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "ticket.priority_changed",
    "filters": { "priority": "Urgent" },
    "url": "https://hooks.example.com/ago"
  }'
```

```json theme={null}
{
  "id": "sub_4f5d4b9f30f28e74a31e8f527925f9c7",
  "object": "event_subscription",
  "event": "ticket.priority_changed",
  "filters": { "priority": "Urgent" },
  "url": "https://hooks.example.com/ago",
  "owner": { "type": "api_key", "name": "Integration" },
  "status": "active",
  "expires_at": null,
  "last_delivery_at": null,
  "last_error": null,
  "failing_since": null,
  "next_attempt_at": null,
  "created_at": "2026-11-21T09:00:00+00:00",
  "truncated": false,
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
}
```

| Field | Description |
| - | - |
| `event` | The event to receive. One event per webhook. |
| `filters` | Optional. Only events whose fields have these values are sent. Text is compared without regard to case. |
| `url` | Your endpoint. It must use HTTPS and be reachable from the internet. |
| `secret` | Optional. The signing secret: `whsec_` followed by 24 to 64 random bytes in base64. Without it, AGO generates one and returns it once, in this response only. |
| `cursor` | Optional. A cursor from an earlier delivery or poll, to also receive the events since then (up to 14 days). |
| `ttl_seconds` | Optional lifetime, at least 300. Without it, an API key's webhook lasts until you delete it. With an OAuth token, a webhook lasts at most 24 hours: create it again to refresh it. |

A webhook is identified by your key, the event, the filters and the URL. Creating it again with the same values refreshes it and keeps its position, so no event is missed or sent twice. With a different `secret`, deliveries are signed with both secrets for 24 hours, so you can switch without rejecting any. Each key can have 50 webhooks.

### Errors

| Status | Code | Meaning |
| - | - | - |
| `400` | `invalid_subscription` | Invalid filters, URL, secret, cursor or lifetime; the message says which |
| `403` | `insufficient_scope` | Your key lacks the scope the event requires |
| `404` | `not_found` | Unknown event, or no webhook with this id for your key |
| `409` | `subscription_limit_reached` | Your key already has 50 webhooks |
| `422` | `endpoint_verification_failed` | Your endpoint did not return the challenge; the message gives the reason: `challenge_failed`, `connection_refused`, `timeout` or `tls_error` |

## Receive deliveries

### Verify the endpoint

When a webhook is created for a new URL, AGO first posts `{ "type": "verification", "challenge": "..." }`. Your endpoint must answer `200` with `{ "challenge": "<the same value>" }`. A URL is verified once per key.

### Check the signature

Every request is signed with the [Standard Webhooks](https://www.standardwebhooks.com/) scheme, so its libraries work too. Check the signature on the raw body, before parsing it, and reject requests older than 5 minutes.

```python theme={null}
import base64
import hashlib
import hmac
import os
import time

SECRET = base64.b64decode(os.environ["AGO_WEBHOOK_SECRET"].removeprefix("whsec_"))


def is_from_ago(headers, body: bytes) -> bool:
    message_id, timestamp = headers["webhook-id"], headers["webhook-timestamp"]
    if abs(time.time() - int(timestamp)) > 300:
        return False
    signed = f"{message_id}.{timestamp}.".encode() + body
    expected = "v1," + base64.b64encode(hmac.new(SECRET, signed, hashlib.sha256).digest()).decode()
    return any(hmac.compare_digest(expected, signature) for signature in headers["webhook-signature"].split())
```

```javascript theme={null}
import crypto from 'node:crypto';

const secret = Buffer.from(process.env.AGO_WEBHOOK_SECRET.replace(/^whsec_/, ''), 'base64');

export function isFromAgo(headers, rawBody) {
    const id = headers['webhook-id'];
    const timestamp = headers['webhook-timestamp'];
    if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
    const expected = Buffer.from(
        'v1,' + crypto.createHmac('sha256', secret).update(`${id}.${timestamp}.`).update(rawBody).digest('base64')
    );
    return headers['webhook-signature']
        .split(' ')
        .some((signature) => signature.length === expected.length && crypto.timingSafeEqual(Buffer.from(signature), expected));
}
```

Then answer with a `2xx` status within 5 seconds, and do the work afterwards. The [MCP Events](https://ago.mintlify.site/api/mcp-events.md#handle-deliveries) page describes the message body, the headers, the `gap` and `terminated` messages, and how retries work.

## Limits

* A webhook receives one event type. Create several to receive several events.
* Events reach your endpoint about 10 seconds after they happen, in order.
* AGO retries a failing delivery for about an hour, then suspends the webhook. Nothing is lost while it is suspended, as long as you resume it within 14 days.
* The delivery history keeps 7 days.
* A webhook is deleted when the API key, OAuth access or admin account that created it is revoked, or loses the scope its event requires. AGO sends a last `terminated` message first.
* Event data identifies what happened. Read the full object with the API or the [MCP tools](https://ago.mintlify.site/api/mcp-tool-api.md), such as `get_ticket`. Treat event data like any API result: it can contain text written by your customers.

## Related

* [MCP Events](https://ago.mintlify.site/api/mcp-events.md)
* [OAuth Scopes](https://ago.mintlify.site/api/oauth-scopes.md)
* [Workflows](https://ago.mintlify.site/features/workflows.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.