Skip to content
alfe.ai

Receive a webhook

Webhooks let your agent react the instant something happens in an external service — a push on GitHub, a paid invoice in Stripe, a new Slack message — instead of polling for changes. In this tutorial you’ll create a webhook, register it with GitHub, and watch your agent receive events. Optionally, you’ll verify the signature in your own receiver.

For the concepts behind everything here, see the Webhooks overview.

Before you start

Section titled “Before you start”

1. Create the webhook

Section titled “1. Create the webhook”

A webhook belongs to exactly one agent and gives it a private inbound URL. Create one either way — both act on the same webhook with the same rules:

  • From the dashboard: open your agent, go to its Webhooks section, and create a webhook. Optionally tag it with the provider (github) so deliveries carry that hint.
  • From the agent itself: ask the agent to create a webhook. Agents have built-in webhook tools and can create and manage their own — an agent can even create the webhook and register it with GitHub in a single task, no human in the loop.

Creating a webhook returns two fields that matter:

{
  "webhookId": "whk_01J9Z8Q…",
  "url": "https://webhooks.alfe.ai/v1/hooks/whk_01J9Z8Q…",
  "signingSecret": "…",
  "provider": "github",
  "active": true
}
  • url is the address you give to GitHub.
  • signingSecret verifies that deliveries genuinely came from Alfe.

2. Register the URL with GitHub

Section titled “2. Register the URL with GitHub”

In your repository, open Settings → Webhooks → Add webhook and set:

  • Payload URL: the webhook url from step 1.
  • Content type: application/json.
  • Events: choose what you care about (for example Just the push event).

Save it. GitHub sends a ping event immediately.

3. Watch your agent receive events

Section titled “3. Watch your agent receive events”

Every inbound delivery is verified by Alfe and handed to your agent in real time. Trigger an event — push a commit — and your agent receives the payload, tagged with the github provider hint so it knows what to expect.

If your agent was offline when an event arrived, the delivery is retained and handed over when it reconnects. You can review recent delivery activity for a webhook to confirm events are arriving — see Delivery and retries.

4. (Optional) Verify signatures in your own receiver

Section titled “4. (Optional) Verify signatures in your own receiver”

If you put your own service in front of the webhook to pre-process events, verify the signature yourself so you only act on authentic requests. Alfe signs every delivery with an X-Alfe-Signature-256 header — an HMAC-SHA256 of the raw request body, keyed with your signing secret:

verify-signature.ts
import crypto from "node:crypto";


function verifyAlfeSignature(rawBody: Buffer, secret: string, signature: string): boolean {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  if (expected.length !== signature.length) return false;
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

The full contract, an Express example, and a Python version are in Verifying signatures.

5. Clean up

Section titled “5. Clean up”

When you’re done, delete the webhook (from the dashboard or via the agent’s tools) — this deactivates its URL, after which inbound requests are rejected with 404. Remove the webhook from GitHub too so it isn’t left calling a dead endpoint.

What you learned

Section titled “What you learned”
  • Each agent gets its own signed, inbound webhook endpoint.
  • You can manage webhooks from the dashboard or let the agent manage its own — both enforce the same per-agent ownership.
  • Deliveries are HMAC-signed and can be verified anywhere the standard HMAC-SHA256 algorithm is available.

Next steps

Section titled “Next steps”