Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runaegis.co/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks let you pipe Aegis governance events into your own systems, incident trackers, on-call tools, audit pipelines, or custom dashboards. When an event fires, Aegis sends a signed JSON payload to every registered endpoint. You verify the signature using your signing secret and process the event however your system needs.

​
Add a webhook endpoint

1

Open webhook settings

In the Aegis dashboard, go to Settings → Webhooks.
2

Enter your endpoint URL

In the Endpoints card, paste your HTTPS endpoint URL into the input field. The URL must be publicly reachable by Aegis.
3

Click Add

Click Add. The endpoint is registered immediately with the default event set: approval and denied. You can see the active events listed next to the endpoint URL.
You can register multiple endpoints. Aegis delivers each event to all registered endpoints in parallel.

​
Supported events

Aegis forwards the following event types to your webhook endpoints:
EventWhen it fires
approvalAn agent action has been held in the approval queue and is waiting for human review.
deniedA policy blocked an agent action from executing.
rewriteAegis redirected an agent action to a safer path, such as converting a direct push into a pull request.
policyA configured governance rule evaluated and fired on an agent action.
anomalyAegis detected unusual behavior in an agent session.
budgetToken spend reached 75%, 90%, or 100% of your configured budget cap.
New endpoints receive approval and denied events by default.

​
Webhook payload structure

Aegis delivers events as HTTP POST requests with a Content-Type: application/json header. Each payload includes the following fields:
FieldTypeDescription
eventstringThe event type: approval, denied, rewrite, policy, anomaly, or budget.
timestampstringISO 8601 timestamp of when the event occurred.
agent_namestringThe name of the agent that triggered the event.
tool_namestringThe GitHub MCP tool the agent called (e.g. create_pull_request, push_files).
decisionstringThe governance decision: ALLOW, DENY, REWRITE, or REQUIRE_APPROVAL.
action_summarystringA plain-language description of what the agent was trying to do.
Example payload: 
{
  "event": "denied",
  "timestamp": "2025-05-21T14:32:07Z",
  "agent_name": "claude-code",
  "tool_name": "push_files",
  "decision": "DENY",
  "action_summary": "Push 3 files to main branch of acme/api, blocked by Protected Branch Denial policy"
}

​
Verify webhook signatures

Every request Aegis sends includes an X-Aegis-Signature header. Use your signing secret to verify the header value before processing the payload, this confirms the request came from Aegis and was not tampered with in transit. Your signing secret is displayed in the Signing secret card under Settings → Webhooks. It starts with whsec_. The verification flow:
1

Read the raw request body

Capture the raw bytes of the POST body before parsing the JSON. Signature verification must run against the raw body, not a re-serialized version.
2

Compute an HMAC-SHA256 digest

Compute HMAC-SHA256(raw_body, signing_secret) using your whsec_... value as the key.
3

Compare to the header

Compare your computed digest to the value in the X-Aegis-Signature header using a constant-time comparison. If they match, the payload is authentic.
import hmac
import hashlib

def verify_aegis_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    key = secret.encode("utf-8")
    expected = hmac.new(key, raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)
Reject any request where the signature does not match. Do not process the payload or return a 200 until verification passes.

​
Rotate your signing secret

If your signing secret is exposed or you want to rotate it as part of regular key hygiene:
  1. Go to Settings → Webhooks.
  2. In the Signing secret card, click Rotate.
  3. Copy the new whsec_... value.
  4. Update your signature verification code with the new secret.
Aegis starts using the new secret immediately after you rotate. Update your verification logic before rotating, or deploy the new secret at the same time. Requests signed with the old secret will fail verification once it is replaced.

​
Webhook failure handling

If your endpoint returns a non-2xx status code or does not respond within the timeout window, Aegis marks the delivery as failed. Aegis retries failed deliveries with exponential backoff. If your endpoint remains unreachable after repeated retries, Aegis marks the webhook as failing, you will see this status badge next to the endpoint URL in Settings → Webhooks.
Return a 200 response as quickly as possible, ideally before doing any processing, to avoid Aegis treating a slow handler as a failure. Handle the event asynchronously in a background job or queue.