Skip to content
alfe.aiDocs

Agent webhooks overview

Agent webhooks give each agent its own inbound HTTP endpoint. When an external system has an event for your agent, its sender or forwarding adapter signs the request and calls that endpoint. Alfe verifies and retains the event before delivering it to your agent.

Think of a webhook as a private mailbox for one agent. You hand its address to a third party, that third party drops signed messages in, and your agent reacts to them as they arrive.

Why use them

Section titled “Why use them”
  • React to real-world events. A push lands on GitHub, an invoice is paid in Stripe, a message is posted in Slack — your agent can act the moment it happens instead of polling.
  • Wire your agent into existing tools. Most SaaS products already speak webhooks. A webhook endpoint is the standard way to let them reach your agent.
  • Let the agent integrate itself. An agent can create its own webhook, get back a URL and secret, and register that URL with an external service programmatically, using a sender that supports the Alfe signature contract.

How a webhook is addressed

Section titled “How a webhook is addressed”

Every webhook has an opaque URL of the form:

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

The <webhookId> is a random, prefixed identifier (for example whk_01J9Z8Q…). It does not contain your agent’s name, your tenant, or any other meaningful identity — so handing the URL to a third party reveals nothing about who owns it. Alfe resolves the URL to the owning agent internally.

How a delivery is secured

Section titled “How a delivery is secured”

Every inbound request is signed. When you create a webhook you get a signing secret that is shared only between you and Alfe. Alfe verifies an X-Alfe-Signature-256 header — an HMAC-SHA256 of the exact request body — on every delivery before it reaches your agent. Requests with a missing or invalid signature are rejected and never delivered.

The signing secret is encrypted at rest and shown to you exactly once, at creation time (and again if you rotate it). Alfe never displays it a second time, so store it somewhere safe.

If you run your own receiver in front of a webhook — for example a small service that pre-processes events — you can verify the same signature yourself. See Verifying signatures.

Supported providers

Section titled “Supported providers”

When you create a webhook you can tag it with the provider that will call it:

Provider Use for
generic Any service that can POST JSON (the default).
github GitHub repository and organization events.
stripe Stripe account events.
slack Slack Events API.

The provider is a hint that travels with each delivery so your agent knows what kind of payload to expect. Signing and delivery work the same way regardless of which provider you choose. These hints do not enable native provider signature verification. A sender must generate X-Alfe-Signature-256, or a forwarding adapter must verify the provider’s own signature before signing a request to Alfe.

What’s next

Section titled “What’s next”