Skip to main content
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: To run an agent at fixed times instead, use the Scheduler API.

​
Base URL

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.

​
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.
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 for code examples.

​
Typical flow

  1. Create a webhook with Create Webhook 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.
  4. If the secret is ever exposed, rotate it with Regenerate Webhook Secret.

​
Errors