Agent webhooks overview

Give an agent its own HTTP endpoint, and your systems can send it events as they happen. The sender signs each request with a shared secret, Alfe verifies it, and the event reaches your agent.

Why use them

Webhooks suit event-driven work:

• React to events. A deploy finishes or an order ships, and your agent can act right away instead of polling.
• Connect your own systems. Anything that can send an HTTP POST and compute an HMAC can reach your agent.
• Let the agent set itself up. An agent can create its own webhook, then use the URL and secret in the automation it’s building.

Senders must sign with the Alfe header

Alfe only accepts requests signed with X-Alfe-Signature-256. GitHub, Stripe, and Slack sign with their own headers, so they can’t call a webhook URL directly. They get a 401.

To receive their events, run a small relay that checks the sender’s signature, then re-signs the body for Alfe. See Webhook signatures.

How a webhook is addressed

Every webhook has an opaque URL:

POST https://webhooks.alfe.ai/v1/hooks/<WEBHOOK_ID>

The ID looks like whk_01J9Z8Q…. It doesn’t contain your agent’s name or your organization, so sharing the URL reveals nothing about who owns it.

How a delivery is secured

Each webhook has a signing secret. The sender uses it to compute an HMAC-SHA256 of the request body and sends the result in the X-Alfe-Signature-256 header. Alfe rejects any request with a missing or invalid signature.

Alfe encrypts the secret at rest. You see it once, when you create the webhook or rotate its secret, so store it somewhere safe.

What happens when an event arrives

Delivery depends on the agent’s runtime:

• OpenClaw — the event starts a turn. The agent sees the webhook’s name, provider, and payload, and decides what to do with its tools. There’s no reply channel back to the sender.
• Terminal runtimes — the event is recorded but doesn’t start a turn. The agent can check each delivery’s status and timing with webhook_list_deliveries, but it doesn’t see the payload.

The provider tag

When you create a webhook, you can tag it with who’s sending:

Provider	Use for
generic	Any sender. This is the default.
github	Events that originate from GitHub.
stripe	Events that originate from Stripe. Alfe uses the body’s id to spot duplicates.
slack	Events that originate from Slack. Alfe uses the body’s event_id to spot duplicates.

The tag travels with each delivery, so the agent knows what kind of payload to expect. It doesn’t change how Alfe verifies signatures.

Next steps

• Create and manage webhooks: set up a webhook and rotate its secret.
• Webhook signatures: sign requests for Alfe, with code examples.
• Delivery and retries: see response codes, duplicate handling, and offline behaviour.