> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# वेबहुक्स

# वेबहुक्स

Gateway बाहरी ट्रिगर्स के लिए एक छोटा HTTP वेबहुक एंडपॉइंट एक्सपोज़ कर सकता है।

## सक्षम करें

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
  },
}
```

टिप्पणियाँ:

* `hooks.token` आवश्यक है जब `hooks.enabled=true`।
* `hooks.path` का डिफ़ॉल्ट मान `/hooks` है।

## प्रमाणीकरण

हर अनुरोध में हुक टोकन शामिल होना चाहिए। हेडर्स को प्राथमिकता दें:

* `Authorization: Bearer <token>` (अनुशंसित)
* `x-openclaw-token: <token>`
* `?token=<token>` (अप्रचलित; एक चेतावनी लॉग करता है और भविष्य के किसी प्रमुख रिलीज़ में हटा दिया जाएगा)

## एंडपॉइंट्स

### `POST /hooks/wake`

पेलोड:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "text": "System line", "mode": "now" }
```

* `text` **आवश्यक** (string): इवेंट का विवरण (उदाहरण: "नया ईमेल प्राप्त हुआ")।
* `mode` वैकल्पिक (`now` | `next-heartbeat`): क्या तुरंत हार्टबीट ट्रिगर करना है (डिफ़ॉल्ट `now`) या अगली आवधिक जाँच का इंतज़ार करना है।

Effect:

* **मुख्य** सत्र के लिए एक सिस्टम इवेंट कतारबद्ध करता है
* यदि `mode=now`, तो तुरंत हार्टबीट ट्रिगर करता है

### `POST /hooks/agent`

पेलोड:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "message": "Run this",
  "name": "Email",
  "sessionKey": "hook:email:msg-123",
  "wakeMode": "now",
  "deliver": true,
  "channel": "last",
  "to": "+15551234567",
  "model": "openai/gpt-5.2-mini",
  "thinking": "low",
  "timeoutSeconds": 120
}
```

* `message` **आवश्यक** (string): एजेंट द्वारा प्रोसेस किया जाने वाला प्रॉम्प्ट या संदेश।
* `name` वैकल्पिक (string): हुक के लिए मानव-पठनीय नाम (उदाहरण: "GitHub"), जिसे सत्र सारांशों में उपसर्ग के रूप में उपयोग किया जाता है।
* `agentId` वैकल्पिक (string): इस हुक को किसी विशिष्ट agent तक रूट करें। अज्ञात ID डिफ़ॉल्ट एजेंट पर वापस चले जाते हैं। सेट होने पर, हुक रेज़ॉल्व किए गए एजेंट के वर्कस्पेस और कॉन्फ़िगरेशन का उपयोग करके चलता है।
* `sessionKey` वैकल्पिक (string): एजेंट के सेशन की पहचान के लिए उपयोग की जाने वाली कुंजी। डिफ़ॉल्ट रूप से यह फ़ील्ड अस्वीकृत होती है जब तक कि `hooks.allowRequestSessionKey=true` सेट न हो।
* `deliver` वैकल्पिक (boolean): यदि `true` है, तो एजेंट का उत्तर मैसेजिंग चैनल पर भेजा जाएगा। डिफ़ॉल्ट `true` है। जो प्रतिक्रियाएँ केवल हार्टबीट स्वीकृतियाँ होती हैं, उन्हें अपने आप छोड़ दिया जाता है।
* `deliver` वैकल्पिक (boolean): यदि `true` है, तो एजेंट का उत्तर मैसेजिंग चैनल पर भेजा जाएगा। डिफ़ॉल्ट `true` है। जो प्रतिक्रियाएँ केवल हार्टबीट स्वीकृतियाँ होती हैं, उन्हें अपने आप छोड़ दिया जाता है।
* `channel` वैकल्पिक (string): डिलीवरी के लिए मैसेजिंग चैनल। इनमें से एक: `last`, `whatsapp`, `telegram`, `discord`, `slack`, `mattermost` (plugin), `signal`, `imessage`, `msteams`. `last` पर डिफ़ॉल्ट होता है।
* `to` वैकल्पिक (string): चैनल के लिए प्राप्तकर्ता पहचानकर्ता (उदा., WhatsApp/Signal के लिए फ़ोन नंबर, Telegram के लिए चैट ID, Discord/Slack/Mattermost (plugin) के लिए चैनल ID, MS Teams के लिए conversation ID)। मुख्य सत्र में अंतिम प्राप्तकर्ता पर डिफ़ॉल्ट होता है।
* `model` वैकल्पिक (string): मॉडल ओवरराइड (उदा., `anthropic/claude-3-5-sonnet` या कोई alias)। यदि प्रतिबंधित हो, तो इसे अनुमत मॉडल सूची में होना चाहिए।
* `timeoutSeconds` वैकल्पिक (number): एजेंट रन की अधिकतम अवधि सेकंड में।
* `timeoutSeconds` वैकल्पिक (number): एजेंट रन की अधिकतम अवधि सेकंड में।

Effect:

* एक **पृथक** एजेंट टर्न चलाता है (स्वयं की सत्र कुंजी)
* हमेशा **मुख्य** सत्र में एक सारांश पोस्ट करता है
* यदि `wakeMode=now`, तो तुरंत हार्टबीट ट्रिगर करता है

## Session key नीति (ब्रेकिंग परिवर्तन)

कस्टम hook नाम `hooks.mappings` के माध्यम से resolved किए जाते हैं (कॉन्फ़िगरेशन देखें)। एक mapping
मनमाने payloads को `wake` या `agent` actions में बदल सकती है, वैकल्पिक templates या
code transforms के साथ।

* अनुशंसित: एक स्थिर `hooks.defaultSessionKey` सेट करें और अनुरोध ओवरराइड्स बंद रखें।
* वैकल्पिक: केवल आवश्यकता होने पर अनुरोध ओवरराइड्स की अनुमति दें, और प्रीफ़िक्स को प्रतिबंधित करें।

अनुशंसित कॉन्फ़िगरेशन:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
  },
}
```

संगतता कॉन्फ़िगरेशन (लीगेसी व्यवहार):

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    allowRequestSessionKey: true,
    allowedSessionKeyPrefixes: ["hook:"], // दृढ़ता से अनुशंसित
  },
}
```

### `POST /hooks/<name>` (mapped)

कस्टम hook नाम `hooks.mappings` के माध्यम से resolved किए जाते हैं (कॉन्फ़िगरेशन देखें)। एक mapping
मनमाने payloads को `wake` या `agent` actions में बदल सकती है, वैकल्पिक templates या
code transforms के साथ।

Mapping options (summary):

* `hooks.presets: ["gmail"]` बिल्ट-इन Gmail मैपिंग सक्षम करता है।
* `hooks.mappings` आपको विन्यास में `match`, `action`, और टेम्पलेट्स परिभाषित करने देता है।
* `hooks.transformsDir` + `transform.module` कस्टम लॉजिक के लिए एक JS/TS मॉड्यूल लोड करता है।
  * `hooks.transformsDir` (यदि सेट किया गया है) आपके OpenClaw कॉन्फ़िगरेशन डायरेक्टरी के अंतर्गत transforms रूट के भीतर ही रहना चाहिए (आमतौर पर `~/.openclaw/hooks/transforms`)।
  * `transform.module` को प्रभावी transforms डायरेक्टरी के भीतर ही रेज़ॉल्व होना चाहिए (traversal/escape पथ अस्वीकृत हैं)।
* `match.source` का उपयोग एक सामान्य इनजेस्ट एंडपॉइंट रखने के लिए करें (payload-आधारित रूटिंग)।
* TS ट्रांसफ़ॉर्म्स के लिए TS लोडर (उदाहरण: `bun` या `tsx`) या रनटाइम पर प्रीकम्पाइल्ड `.js` आवश्यक है।
* मैपिंग्स पर `deliver: true` + `channel`/`to` सेट करें ताकि उत्तरों को किसी चैट सतह पर रूट किया जा सके
  (`channel` का डिफ़ॉल्ट `last` है और बैकअप के रूप में WhatsApp पर गिरता है)।
* `agentId` हुक को एक विशिष्ट एजेंट की ओर रूट करता है; अज्ञात ID डिफ़ॉल्ट एजेंट पर वापस चले जाते हैं।
* `hooks.allowedAgentIds` स्पष्ट `agentId` रूटिंग को प्रतिबंधित करता है। किसी भी एजेंट की अनुमति देने के लिए इसे छोड़ दें (या `*` शामिल करें)। स्पष्ट `agentId` रूटिंग को अस्वीकार करने के लिए `[]` सेट करें।
* `hooks.defaultSessionKey` तब हुक एजेंट रन के लिए डिफ़ॉल्ट सेशन सेट करता है जब कोई स्पष्ट कुंजी प्रदान नहीं की जाती।
* `hooks.allowRequestSessionKey` यह नियंत्रित करता है कि क्या `/hooks/agent` payloads `sessionKey` सेट कर सकते हैं (डिफ़ॉल्ट: `false`)।
* `hooks.allowedSessionKeyPrefixes` वैकल्पिक रूप से अनुरोध payloads और mappings से स्पष्ट `sessionKey` मानों को प्रतिबंधित करता है।
* `allowUnsafeExternalContent: true` उस हुक के लिए बाहरी सामग्री सुरक्षा रैपर को अक्षम करता है
  (खतरनाक; केवल विश्वसनीय आंतरिक स्रोतों के लिए)।
* `openclaw webhooks gmail setup`, `openclaw webhooks gmail run` के लिए `hooks.gmail` कॉन्फ़िग लिखता है।
  पूर्ण Gmail watch flow के लिए [Gmail Pub/Sub](/automation/gmail-pubsub) देखें।

## Responses

* `/hooks/wake` के लिए `200`
* `/hooks/agent` के लिए `202` (async रन शुरू हुआ)
* प्रमाणीकरण विफलता पर `401`
* उसी क्लाइंट से बार-बार auth विफलताओं के बाद `429` ( `Retry-After` जांचें )
* अमान्य payload पर `400`
* अत्यधिक बड़े payloads पर `413`

## Examples

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"New email received","mode":"now"}'
```

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","wakeMode":"next-heartbeat"}'
```

### Use a different model

उस रन के लिए मॉडल ओवरराइड करने हेतु एजेंट payload (या मैपिंग) में `model` जोड़ें:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.2-mini"}'
```

यदि आप `agents.defaults.models` लागू करते हैं, तो सुनिश्चित करें कि ओवरराइड मॉडल उसमें शामिल है।

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -X POST http://127.0.0.1:18789/hooks/gmail \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"source":"gmail","messages":[{"from":"Ada","subject":"Hello","snippet":"Hi"}]}'
```

## Security

* हुक एंडपॉइंट्स को loopback, tailnet, या विश्वसनीय रिवर्स प्रॉक्सी के पीछे रखें।
* एक समर्पित हुक टोकन का उपयोग करें; Gateway प्रमाणीकरण टोकनों का पुनः उपयोग न करें।
* बार-बार auth विफलताओं को brute-force प्रयासों को धीमा करने के लिए प्रति क्लाइंट पते पर rate-limit किया जाता है।
* यदि आप multi-agent routing का उपयोग करते हैं, तो स्पष्ट `agentId` चयन को सीमित करने के लिए `hooks.allowedAgentIds` सेट करें।
* जब तक आपको caller-चयनित सेशन की आवश्यकता न हो, `hooks.allowRequestSessionKey=false` रखें।
* यदि आप अनुरोध `sessionKey` सक्षम करते हैं, तो `hooks.allowedSessionKeyPrefixes` को प्रतिबंधित करें (उदाहरण के लिए, `["hook:"]`)।
* वेबहुक लॉग्स में संवेदनशील कच्चे payloads शामिल करने से बचें।
* Hook payloads को डिफ़ॉल्ट रूप से अविश्वसनीय माना जाता है और सुरक्षा सीमाओं के साथ wrap किया जाता है।
  यदि किसी विशेष hook के लिए इसे अक्षम करना आवश्यक हो, तो उस hook की mapping में
  `allowUnsafeExternalContent: true`
  सेट करें (खतरनाक)।