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

# Webhooks API

> Trigger agents from external systems with signed HTTP requests.

A webhook gives an agent its own URL. When an external system, such as a ticketing tool, a form, a CI pipeline, or GitHub, sends a signed `POST` request to that URL, the agent runs with the request's JSON body as its message.

The Webhooks API has two parts:

| Group | What it does |
| - | - |
| [Agent Webhooks](/enterprise/api/webhooks/agent-webhooks/create) | Create and manage webhooks: get the URL and secret, pause, resume, rotate the secret, and read run history. |
| [Webhook Trigger](/enterprise/api/webhooks/webhook-trigger/trigger) | The public endpoint external systems call to run the agent. |

To run an agent at fixed times instead, use the [Scheduler API](/enterprise/api/scheduler/introduction).

## Base URL

```text theme={null}
https://scheduler.studio.lyzr.ai
```

<Note>
  Collection endpoints end in a trailing slash, for example `/agent-webhooks/` and `/agent-webhooks/pause-bulk/`. Include it exactly as shown. Requests without it are redirected, and most HTTP clients drop the body and headers when they follow the redirect.
</Note>

## Authentication

The two parts authenticate differently.

**Agent Webhooks** endpoints require your Lyzr API key in the `x-api-key` header. Webhooks are scoped to the key that created them.

```bash theme={null}
curl https://scheduler.studio.lyzr.ai/agent-webhooks/ \
  -H "x-api-key: YOUR_API_KEY"
```

**Webhook Trigger** does not take an API key, so you never have to share your key with the external system. Instead, each request is signed with the webhook's `secret_key`: send `X-Webhook-Signature: sha256=<hex_digest>`, where the digest is the HMAC-SHA256 of the raw request body. See [Trigger Webhook](/enterprise/api/webhooks/webhook-trigger/trigger) for code examples.

## Typical flow

1. Create a webhook with [Create Webhook](/enterprise/api/webhooks/agent-webhooks/create) and store the returned `webhook_url` and `secret_key`.
2. Configure the external system to `POST` JSON to `webhook_url`, signed with `secret_key`.
3. Monitor runs with [List Recent Webhook Executions](/enterprise/api/webhooks/agent-webhooks/recent-executions).
4. If the secret is ever exposed, rotate it with [Regenerate Webhook Secret](/enterprise/api/webhooks/agent-webhooks/regenerate-secret).

## Errors

| Status | Meaning |
| - | - |
| `401` | Webhook Trigger only: the signature is missing, malformed, or does not match the body. |
| `403` | Agent Webhooks only: the `x-api-key` header is missing or invalid. |
| `404` | No webhook with that ID exists. |
| `422` | The request failed validation. The `detail` array lists each invalid field. |