ब्लॉग · गाइड · 29 अक्टूबर 2026
साइन किए गए webhook से AEGIS वर्कफ़्लो शुरू करें
प्रकटीकरण: AEGIS को 100monkeys.ai बनाता है, इसलिए इस गाइड को बनाने वाले का विवरण मानकर पढ़ें। इसका मसौदा हमारे एक AI एजेंट ने सार्वजनिक AEGIS दस्तावेज़ Configuring Webhooks से तैयार किया, और कंपनी ने इसकी समीक्षा की; यह हिन्दी संस्करण मूल अंग्रेज़ी गाइड का अनुवाद है। नीचे हर कमांड और कोड ब्लॉक उसी पेज से कॉपी किया गया है; इस गाइड के लिए कोई भी चलाया नहीं गया। उद्धरण अंग्रेज़ी में हैं और अनुवाद साथ में दिया है। जहाँ दस्तावेज़ कोई सवाल खुला छोड़ते हैं, आख़िरी हिस्सा वह बताता है।
AEGIS by 100monkeys.ai, in beta, तब एक वर्कफ़्लो शुरू कर सकता है जब कोई दूसरा सिस्टम उसे एक इवेंट भेजे: GitHub पर एक push, किसी CI जॉब का पूरा होना, या कोई भी सेवा जो HTTP रिक्वेस्ट भेज सकती है। भेजने वाले को आपके नोड पर किसी खाते की ज़रूरत नहीं। दस्तावेज़ों के शब्दों में, "Authentication is handled by HMAC-SHA256 signature verification, not OAuth." (प्रमाणीकरण HMAC-SHA256 सिग्नेचर की जाँच से होता है, OAuth से नहीं।) यह गाइड साझा सीक्रेट से लेकर एक जाँची हुई रिक्वेस्ट तक एक स्रोत को पूरा सेट करती है, और रास्ते में मिलने वाली एररों को समझाती है।
कदम 1. स्रोत का नाम तय करें
हर webhook POST /v1/webhooks/{source} पर आता है। स्रोत "a lowercase slug that identifies the system sending the event" (इवेंट भेजने वाले सिस्टम को पहचानने वाला छोटे अक्षरों का slug) है, जैसे github, stripe या my-ci। हर भेजने वाले सिस्टम के लिए एक चुनें: सीक्रेट, रूट और दोहराव की जाँच, तीनों इसी पर टिके हैं।
कदम 2. ऑर्केस्ट्रेटर पर साझा सीक्रेट सेट करें
सीक्रेट हर टेनेंट और स्रोत के लिए अलग होते हैं, इसलिए दो टेनेंट जो दोनों अपने स्रोत को github कहते हैं, "completely independent secrets" (पूरी तरह अलग सीक्रेट) रखते हैं। हर जोड़ी ऑर्केस्ट्रेटर पर एक एनवायरनमेंट वेरिएबल है, जिसका नाम इस पैटर्न पर बनता है:
# 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"तो टेनेंट u-abc123 और स्रोत my-ci के लिए वेरिएबल AEGIS_WEBHOOK_SECRET_U_ABC123_MY_CI पढ़ा जाता है। अगर तय हुई जोड़ी के लिए वेरिएबल नहीं है, तो रिक्वेस्ट 401 secret_not_found के साथ अस्वीकार होती है। वही सीक्रेट भेजने वाले को दें और किसी और को नहीं।
कदम 3. स्रोत को एक वर्कफ़्लो तक रूट करें
सीधा रूट स्रोत को एक वर्कफ़्लो से जोड़ता है, इसलिए रूटिंग "instant and deterministic" (तुरंत और निर्धारक) होती है। मौजूदा रिलीज़ में सीधे रूट "configured via orchestrator workflow routing configuration" (ऑर्केस्ट्रेटर के वर्कफ़्लो रूटिंग कॉन्फ़िगरेशन से सेट होते हैं), और पेज बताता है कि "there is no aegis stimulus routes CLI command yet" (अभी aegis stimulus routes नाम की CLI कमांड नहीं है)। सीधा रूट न हो तो पाइपलाइन किसी कॉन्फ़िगर किए गए RouterAgent पर लौटती है, जो इवेंट को एक भाषा मॉडल से वर्गीकृत करता है। दोनों न हों तो रिक्वेस्ट 422 no_router_configured के साथ फ़ेल होती है। एक अकेले, जाने-पहचाने भेजने वाले के लिए सीधा रूट ही ठीक है: एक ही इवेंट हमेशा एक ही वर्कफ़्लो शुरू करता है।
कदम 4. भेजने वाले पर raw बॉडी साइन करें
भेजने वाला साझा सीक्रेट से रिक्वेस्ट की raw बॉडी का HMAC-SHA256 निकालता है और उसे sha256= उपसर्ग के साथ X-Aegis-Signature में भेजता है। दस्तावेज़ों का Python उदाहरण:
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,
},
)पेज यही Node.js में भी देता है। जिस एक नियम को वह बोल्ड में रखता है: किसी भी पार्सिंग से पहले, रिक्वेस्ट बॉडी के raw बाइट्स पर HMAC निकालें, क्योंकि "Computing over a re-serialized object will produce a different signature." (दोबारा सीरियलाइज़ किए गए ऑब्जेक्ट पर निकालने से अलग सिग्नेचर बनेगा।) ठीक वही बाइट्स साइन करें जो आप भेजते हैं।
कदम 5. curl से एंडपॉइंट जाँचें
# 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"सफल होने पर दो id लौटती हैं:
{
"stimulus_id": "stim-uuid",
"workflow_execution_id": "wfex-uuid"
}दूसरी id उस वर्कफ़्लो रन की है जो इवेंट ने शुरू किया; उसे किसी भी दूसरे रन की तरह फ़ॉलो करें।
कदम 6. दोहराई गई डिलीवरी रोकें
भेजने वाले दोबारा कोशिश करते हैं। प्रोवाइडर की डिलीवरी id को X-Idempotency-Key के रूप में आगे भेजें: GitHub के लिए यह X-GitHub-Delivery है, और आपके अपने भेजने वाले के लिए "Any stable per-event UUID" (हर इवेंट के लिए कोई भी स्थिर UUID)। ऑर्केस्ट्रेटर स्रोत और key पर 24 घंटे तक दोहराव हटाता है, और दोहराई गई रिक्वेस्ट को 409 मिलता है:
{
"error": "idempotent_duplicate",
"original_stimulus_id": "stim-original-uuid"
}कदम 7. मिली हुई एरर पढ़ें
पेज की एरर तालिका, उसी क्रम में जिसमें आप उनसे शायद मिलेंगे:
401 missing_signature:X-Aegis-Signatureहेडर नहीं है।400 malformed_signature: हेडरsha256=<hex>रूप में नहीं है;400 invalid_hex: hex हिस्से में दूसरे अक्षर हैं।401 secret_not_found: तय हुए टेनेंट और स्रोत के लिए कोई वेरिएबल नहीं।401 invalid_signature: डाइजेस्ट मेल नहीं खाता; साइन करने से पहले दोबारा सीरियलाइज़ हुई बॉडी वही मामला है जिसकी चेतावनी पेज देता है।409 idempotent_duplicate: 24 घंटे के भीतर पहले ही प्रोसेस हो चुका।422 classification_failed: RouterAgent का भरोसा उसकी सीमा से कम था;422 no_router_configured: न सीधा रूट, न RouterAgent।
कदम 8. आंतरिक कॉलर के लिए प्रमाणित एंडपॉइंट इस्तेमाल करें
जिस सेवा के पास पहले से Keycloak खाता है, वह साझा सीक्रेट छोड़कर bearer token के साथ POST /v1/stimuli पर भेज सकती है, और बॉडी में source, content और एक idempotency_key दे सकती है। webhook रूट उन सिस्टमों के लिए रखें जिन्हें आप नहीं चलाते।
दस्तावेज़ क्या खुला छोड़ते हैं
- सीधा रूट कैसे लिखें। पेज कहता है कि रूट ऑर्केस्ट्रेटर के वर्कफ़्लो रूटिंग कॉन्फ़िगरेशन में रहते हैं, पर कोई key, फ़ाइल या उदाहरण नहीं देता, और उस कदम से Configuration Reference का लिंक भी नहीं है।
- webhook कैसे रजिस्टर होता है। टेनेंट "is resolved from the (tenant, source_name) registration written when the webhook was registered" (webhook रजिस्टर करते समय लिखे गए (tenant, source_name) रजिस्ट्रेशन से तय होता है); पेज वह रजिस्ट्रेशन नहीं दिखाता।
- वर्कफ़्लो को क्या मिलता है। पेज नहीं बताता कि पेलोड और हेडर शुरू हुए वर्कफ़्लो के इनपुट या blackboard में कैसे दिखते हैं।
- सीक्रेट बदलना। पुराने और नए सीक्रेट के साथ चलने की कोई अवधि नहीं बताई गई, और पेज यह नहीं बताता कि बदला हुआ वेरिएबल ऑर्केस्ट्रेटर रीस्टार्ट किए बिना लागू होता है या नहीं।
आगे
webhook जो वर्कफ़्लो शुरू करता है, वह आपकी लिखी एक स्टेट मशीन है। हमारी गाइड AEGIS वर्कफ़्लो की स्टेटें और ट्रांज़िशन, कदम दर कदम एक बनाती है। AEGIS उस कमांड से इंस्टॉल होता है जो 100monkeys.ai पर छपी है:
curl -fsSL https://get.100monkeys.ai | bash