Webhooks

Overview

Webhooks let external systems push events into ArchAgents so your agents can react to them.

Use a webhook when:

• a third-party product (GitHub, Slack, or your own service) emits an event you want an agent to act on
• you want incoming payloads to become indexed context the agent can search later
• the trigger lives outside the platform and you would otherwise have to poll for it

The platform verifies every incoming request with a signing secret you set, so webhooks fail closed if a payload is unsigned, expired, or forged.

---

Create a webhook

archagent create webhook \
 --provider github \
 --signing-secret <secret> \
 --enabled

Three fields drive the behavior:

Option	What it does
--provider <github|slack>	Use a built-in provider's verification and event shape. The platform knows how to verify GitHub's X-Hub-Signature-256 and Slack's X-Slack-Signature headers.
--lookup-key <key>	For generic webhooks. Use any service you control, set the lookup key to something you can reference later (e.g. acme-billing).
--signing-secret <secret>	Required. The shared secret the sender uses to sign requests. Rotate it with update webhook -s <new-secret> whenever you rotate it on the sender side.

Add --provision-context-source to auto-create an inbound context source connected to this webhook. Useful when the events should also become searchable context for an agent.

Inspect what you have:

archagent list webhooks
archagent describe webhook <webhook_id>

---

Inspect events

Every incoming request is recorded. Inspect the history when you are debugging "did the webhook actually fire?":

archagent list webhookevents --webhook <webhook_id>

The list shows arrival time, signature verification status, the event type, and any downstream dispatch outcome.

---

React to webhook events

Once a webhook is set up, an agent reacts in one of two ways:

• Trigger a routine. A routine with a webhook event type fires whenever a matching event arrives. This is the path for "do something when X happens upstream."
• Ingest into context. When you create the webhook with --provision-context-source, payloads are also indexed as a knowledge source the agent can search later. This is the path for "make these events part of what the agent can see."

Both paths can run from the same webhook. Use the routine for the immediate reaction, and the context source for the long-term knowledge.

---

Update or delete

archagent update webhook <webhook_id> --enabled false
archagent update webhook <webhook_id> --signing-secret <new-secret>
archagent delete webhook <webhook_id>

Disabling is reversible; deleting is not. Disable first if you suspect a misbehaving sender: events stop dispatching but the configuration stays in place for inspection.

---

Security and signing

A webhook without a working signing secret is effectively a public POST endpoint, so every webhook in ArchAgents requires one and verifies it on every request. Failed verifications are recorded in the event list with an explicit failure reason; they never reach a routine or context source.

Rotate the signing secret on the sender first, then update the webhook on the platform side. Until both sides agree, requests will be rejected, which is the correct fail-closed behavior.

---

Where to go next

1. Installations: for OAuth-backed integrations (GitHub App, Slack, Gmail) that go beyond a single webhook URL.
2. Knowledge: when webhook payloads should also become indexed context.
3. Agents: for the routine model that dispatches off webhook events.