100monkeys.ai

Blog · Anleitung · 29. Oktober 2026

Einen AEGIS-Workflow per signiertem Webhook starten

Auch auf: English, Español, Português, 日本語, Français, 한국어, 简体中文, Italiano, हिन्दी · Alle Anleitungen auf Deutsch

Offenlegung: Wir bei 100monkeys.ai entwickeln AEGIS, lesen Sie diese Anleitung also als Bericht des Herstellers. Einer unserer KI-Agenten hat sie aus der öffentlichen AEGIS-Dokumentation (auf Englisch) entworfen, der Seite Configuring Webhooks, und das Unternehmen hat sie geprüft; diese deutsche Fassung ist eine Übersetzung der englischen Originalanleitung. Jeder Befehl und jeder Codeblock unten ist von dieser Seite kopiert; für diese Anleitung wurde nichts davon ausgeführt. Zitate bleiben auf Englisch, mit der Übersetzung daneben. Wo die Dokumentation eine Frage offen lässt, sagt es der letzte Abschnitt.

AEGIS by 100monkeys.ai, in beta, kann einen Workflow starten, wenn ein anderes System ihm ein Ereignis schickt: ein Push auf GitHub, ein fertiger CI-Job, jeder Dienst, der eine HTTP-Anfrage stellen kann. Der Absender braucht kein Konto auf Ihrem Knoten. In den Worten der Dokumentation: "Authentication is handled by HMAC-SHA256 signature verification, not OAuth." (Die Authentifizierung erfolgt über die Prüfung einer HMAC-SHA256-Signatur, nicht über OAuth.) Diese Anleitung richtet eine Quelle von Anfang bis Ende ein, vom gemeinsamen Secret bis zur getesteten Anfrage, und behandelt die Fehler, denen Sie unterwegs begegnen.

Schritt 1. Die Quelle benennen

Jeder Webhook kommt bei POST /v1/webhooks/{source} an. Die Quelle ist "a lowercase slug that identifies the system sending the event" (ein Slug in Kleinbuchstaben, der das sendende System bezeichnet), etwa github, stripe oder my-ci. Wählen Sie einen pro sendendem System: Secret, Route und Dublettenprüfung hängen alle daran.

Schritt 2. Das gemeinsame Secret am Orchestrator setzen

Secrets gelten pro Mandant und Quelle; zwei Mandanten, die ihre Quelle beide github nennen, halten also "completely independent secrets" (völlig unabhängige Secrets). Jedes Paar ist eine Umgebungsvariable am Orchestrator, benannt nach diesem Muster:

# Pattern: AEGIS_WEBHOOK_SECRET_<UPPER_TENANT>_<UPPER_SOURCE>
# Hyphens and dots in tenant id and source name are replaced with underscores

export AEGIS_WEBHOOK_SECRET_U_ABC123_GITHUB="your-shared-secret-here"
export AEGIS_WEBHOOK_SECRET_U_ABC123_STRIPE="another-secret"
export AEGIS_WEBHOOK_SECRET_U_DEF456_MY_CI="third-secret"

Mandant u-abc123 mit der Quelle my-ci liest also AEGIS_WEBHOOK_SECRET_U_ABC123_MY_CI. Fehlt die Variable für das ermittelte Paar, wird die Anfrage mit 401 secret_not_found abgelehnt. Geben Sie dasselbe Secret dem Absender und sonst niemandem.

Schritt 3. Die Quelle an einen Workflow leiten

Eine direkte Route bildet die Quelle auf einen Workflow ab, das Routing ist also "instant and deterministic" (sofort und deterministisch). In der aktuellen Version werden direkte Routen "configured via orchestrator workflow routing configuration" (über die Workflow-Routing-Konfiguration des Orchestrators eingestellt), und die Seite merkt an: "there is no aegis stimulus routes CLI command yet" (es gibt noch keinen CLI-Befehl aegis stimulus routes). Ohne direkte Route greift die Pipeline auf einen konfigurierten RouterAgent zurück, der das Ereignis mit einem Sprachmodell einordnet. Fehlt beides, scheitert die Anfrage mit 422 no_router_configured. Für einen einzelnen, bekannten Absender ist die direkte Route die richtige: Dasselbe Ereignis startet immer denselben Workflow.

Schritt 4. Den rohen Body beim Absender signieren

Der Absender berechnet mit dem gemeinsamen Secret einen HMAC-SHA256 über den rohen Anfrage-Body und schickt ihn in X-Aegis-Signature mit dem Präfix sha256=. Das Python-Beispiel der Dokumentation:

import hashlib
import hmac
import json
import requests

def sign_payload(body: bytes, secret: str) -> str:
    sig = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return f"sha256={sig}"

payload = json.dumps({"event": "push", "ref": "refs/heads/main"}).encode()
signature = sign_payload(payload, WEBHOOK_SECRET)

requests.post(
    "https://your-aegis-node/v1/webhooks/github",
    data=payload,
    headers={
        "Content-Type": "application/json",
        "X-Aegis-Signature": signature,
    },
)

Die Seite zeigt dasselbe auch in Node.js. Die eine Regel, die sie fett setzt: den HMAC über die rohen Bytes des Bodys berechnen, vor jedem Parsen, denn "Computing over a re-serialized object will produce a different signature." (Über ein neu serialisiertes Objekt berechnet, ergibt sich eine andere Signatur.) Signieren Sie genau die Bytes, die Sie senden.

Schritt 5. Den Endpunkt mit curl testen

# Generate a test signature
SECRET="your-shared-secret-here"
BODY='{"event":"push","ref":"refs/heads/main"}'
SIG="sha256=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')"

# Send the test webhook
curl -X POST https://your-aegis-node/v1/webhooks/github \
  -H "Content-Type: application/json" \
  -H "X-Aegis-Signature: $SIG" \
  -d "$BODY"

Ein Erfolg antwortet mit zwei IDs:

{
  "stimulus_id": "stim-uuid",
  "workflow_execution_id": "wfex-uuid"
}

Die zweite ist der Workflow-Lauf, den das Ereignis gestartet hat; verfolgen Sie ihn wie jeden anderen Lauf.

Schritt 6. Doppelte Zustellungen stoppen

Absender wiederholen Zustellungen. Reichen Sie die Zustell-ID des Anbieters als X-Idempotency-Key weiter: bei GitHub ist das X-GitHub-Delivery, bei Ihrem eigenen Absender "Any stable per-event UUID" (jede stabile UUID pro Ereignis). Der Orchestrator dedupliziert 24 Stunden lang nach Quelle und Schlüssel, und eine Wiederholung antwortet mit 409:

{
  "error": "idempotent_duplicate",
  "original_stimulus_id": "stim-original-uuid"
}

Schritt 7. Den Fehler lesen, den Sie bekommen

Die Fehlertabelle der Seite, in der Reihenfolge, in der Sie ihr wahrscheinlich begegnen:

Schritt 8. Für interne Aufrufer den authentifizierten Endpunkt nutzen

Ein Dienst, der bereits ein Keycloak-Konto hat, kann das gemeinsame Secret auslassen und stattdessen mit einem Bearer-Token an POST /v1/stimuli senden, mit source, content und einem idempotency_key im Body. Behalten Sie die Webhook-Route für Systeme, die Sie nicht selbst betreiben.

Was die Dokumentation offen lässt

Weiter

Der Workflow, den ein Webhook startet, ist ein Zustandsautomat, den Sie schreiben. Unsere Anleitung AEGIS-Workflow-Zustände und -Übergänge, Schritt für Schritt baut einen. AEGIS wird mit dem Befehl installiert, der auf 100monkeys.ai steht:

curl -fsSL https://get.100monkeys.ai | bash

AEGIS von 100monkeys.ai installieren