Skip to content
alfe.ai

Agent webhooks overview

Agent webhooks give each agent its own inbound HTTP endpoint. When an external service — GitHub, Stripe, Slack, or anything that can POST JSON — has an event for your agent, it calls that endpoint, Alfe verifies the request, and the payload is delivered to your agent in real time.

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 — no human in the loop.

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.

What’s next

Section titled “What’s next”