Create and manage webhooks

Webhooks are managed by the agent that owns them, through its tools or the Agent API. There’s no webhooks screen in the dashboard, so ask your agent to do this, or call the API with its key.

Choose how to manage them

Use whichever fits your setup:

Action	Agent tool (terminal runtimes)	AgentApiClient method	Agent API route
Create	webhook_create	createWebhook	POST /agent/webhooks
List	webhook_list	listWebhooks	GET /agent/webhooks
Rotate the secret	webhook_rotate_secret	rotateWebhookSecret	POST /agent/webhooks/<WEBHOOK_ID>/rotate
Delete	webhook_delete	deleteWebhook	DELETE /agent/webhooks/<WEBHOOK_ID>
List deliveries	webhook_list_deliveries	listWebhookDeliveries	GET /agent/webhooks/<WEBHOOK_ID>/deliveries

A webhook always belongs to the agent whose key made the request. See the Agent API webhooks reference for details and authentication.

Create a webhook

Provide:

• name — a label from 1 to 100 characters.
• provider — optional. One of generic, github, stripe, or slack. The default is generic.

create-webhook.ts

const webhook = await client.createWebhook({
  name: "Deploy events",
  provider: "generic",
});

console.log(webhook.url); // Give this to your sender.
// Store webhook.signingSecret securely. You won't see it again.

The response includes:

Response

{
  "webhookId": "whk_01J9Z8Q…",
  "url": "https://webhooks.alfe.ai/v1/hooks/whk_01J9Z8Q…",
  "signingSecret": "<SIGNING_SECRET>",
  "name": "Deploy events",
  "provider": "generic",
  "active": true,
  "createdAt": "2026-07-01T12:00:00.000Z"
}

Two fields matter most:

• url — where your sender posts events.
• signingSecret — how your sender signs them. Alfe shows it once. If you lose it, rotate the secret.

Then set up your sender. See Webhook signatures.

List webhooks

Listing returns each webhook’s ID, name, provider, active state, creator, and timestamps. It never returns the signing secret.

Rotate the signing secret

Rotating replaces the secret and returns the new one, once:

Response

{ "webhookId": "whk_01J9Z8Q…", "signingSecret": "<NEW_SIGNING_SECRET>" }

Rotate when a secret may have been exposed, or on a routine schedule. The URL and ID stay the same.

Caution

The old secret stops working as soon as you rotate. Requests signed with it get a 401 until you update your sender.

Delete a webhook

Deleting deactivates the webhook, and its URL starts returning 404. Remove the URL from your sender too, so it isn’t left calling a dead endpoint.

Review deliveries

Listing deliveries shows recent events for a webhook, with each one’s status, attempt count, and timestamps. A delivery’s status is one of pending, delivered, failed, or expired. See Delivery and retries.

Ownership and access

Every webhook belongs to one agent. A request for a webhook another agent owns returns not found, not forbidden, so nobody can probe for webhooks they don’t own.

Next steps

• Webhook signatures: sign requests for Alfe.
• Delivery and retries: see how events reach your agent.