एंडपॉइंट
`webhooks.list`, `get`, `create`, `update`, `delete`, `rotateSecret`, `test` और `listDeliveries`।
हर method
const endpoint = await openemail.webhooks.create({ url: 'https://acme.com/hooks/mail', eventTypes: ['email.sent', 'email.bounced'], description: 'Billing service',}) await store(endpoint.secret) await openemail.webhooks.list()await openemail.webhooks.get(endpoint.id)await openemail.webhooks.update(endpoint.id, { enabled: false })await openemail.webhooks.test(endpoint.id)const rotated = await openemail.webhooks.rotateSecret(endpoint.id)await openemail.webhooks.delete(endpoint.id)rotateSecret को छोड़कर create ही अकेली बार है जब secret लौटाया जाता है। कोई read उसे कभी नहीं दोहराता, इसलिए बाकी कुछ भी करने से पहले उसे संग्रहीत करें। हर event पाने के लिए eventTypes छोड़ दें, बाद वाले भी शामिल।
rotateSecret में कोई overlap विंडो नहीं है। पुराना secret तुरंत काम करना बंद कर देता है, इसलिए rotate करने से पहले नया तैनात करें। इसे कभी अपने आप retry नहीं किया जाता: retry दूसरी बार rotate कर देता और उस secret को रद्द कर देता जो पहली कोशिश ने लौटाया था।
आप किसकी सदस्यता ले सकते हैं
WEBHOOK_EVENTS export किया गया है ताकि आप सूची दिखा सकें। ये events **मेलबॉक्स** के हैं, इस API के नहीं: email.received उस मेल पर चलता है जो ऐप में आती है, और email.sent उस संदेश पर जिसे composer ने भेजा। सदस्यता लेना अपने API ट्रैफ़िक को देखने जैसा नहीं है।
यह साबित करना कि यह काम करता है
const result = await openemail.webhooks.test('whe_…')console.log(result.delivery?.status, result.delivery?.responseCode) const deliveries = await openemail.webhooks.listDeliveries('whe_…')for (const d of deliveries) console.log(d.eventType, d.status, d.responseCode, d.error)null वाले responseCode का मतलब है कि रिस्पॉन्स आया ही नहीं (DNS, TLS, कोई timeout), जो उस रिस्पॉन्स से अलग तथ्य है जिसने 0 कहा। हर पंक्ति attempt और maxAttempts लिए चलती है, इसलिए कई पंक्तियाँ एक ही event का वर्णन कर सकती हैं: उन सब पर एक जैसी payload.id ही event है, और कोशिश की संख्या प्रयास है।
पैरामीटर: webhooks.create
urlstringआवश्यक- जहाँ deliveries POST की जाती हैं। केवल HTTPS, और host न `localhost` हो सकता है, न `.localhost`/`.local`/`.internal` नाम, और न loopback, private, CGNAT या link-local IP literal। यह आपके दिए पते पर सर्वर की ओर से किया गया fetch है, इसलिए वे `url` पर 422 हैं; जाँच hostname को जैसा लिखा है वैसा पढ़ती है और DNS कभी हल नहीं करती। जो संग्रहीत होता है वह आपके भेजे का URL parser वाला serialisation है, इसलिए `https://acme.com` वापस `https://acme.com/` पढ़ा जाता है।
eventTypesWebhookEvent[]- इस endpoint तक कौन-से events पहुँचते हैं: `WEBHOOK_EVENTS` के किसी भी नाम। `POST /webhooks` array को मौजूद events की संख्या पर सीमित करता है, इसलिए उससे एक ज़्यादा `eventTypes` पर 422 है; `PATCH` उसे सीमित नहीं करता। केवल लंबाई सीमित है, और दोहराया गया नाम हूबहू वैसा ही संग्रहीत और वापस पढ़ा जाता है जैसा आपने भेजा। छोड़ा गया या खाली, खाली सूची के रूप में संग्रहीत होता है, इसीलिए वह वापस `['*']` पढ़ा जाता है, और उसका अर्थ है `email.replied` को छोड़कर हर `email.*` event — आज चौदह — और कभी भी domain या suppression परिवार नहीं। बाद में जोड़ा गया कोई परिवार उस endpoint तक कभी नहीं पहुँचता जिसने उसका नाम नहीं लिया, इसलिए किसी रिलीज़ के कारण कोई integration ऐसा आकार पाना शुरू नहीं कर सकता जो उसने कभी देखा ही नहीं।
descriptionstring- endpoint के लिए एक लेबल, अधिकतम 200 वर्ण, ताकि webhooks की सूची URL के स्तंभ के बजाय नामों की तरह पढ़ी जाए। छोड़ने पर यह null के रूप में संग्रहीत और लौटाया जाता है।
रिस्पॉन्स: CreatedWebhookResource
object'webhook'- हमेशा `'webhook'`, वही discriminator जो सादा read लौटाता है, क्योंकि secret सामान्य आकार पर एक अतिरिक्त key है, अपने आप में कोई object type नहीं। `secret` मौजूद है या नहीं, यह इस फ़ील्ड से नहीं बल्कि इससे तय होता है कि आपने कौन-सा method कॉल किया।
idstring- endpoint का पहचानकर्ता: `whe_` के बाद 24 hex वर्ण। बाकी हर webhook कॉल इसे लेता है: `get`, `update`, `delete`, `rotateSecret`, `test` और `listDeliveries`।
urlstring- endpoint जैसा संग्रहीत है, HTTPS और अवरुद्ध-host जाँचें पार करने के बाद। यह पार्स किया गया URL फिर से serialise किया हुआ है, इसलिए अपनी भेजी string से नहीं, इसी मान से तुलना करें।
descriptionstring | null- जो लेबल आपने दिया, या null अगर कोई नहीं दिया। स्पष्ट null भेजने वाला `update` इसे वापस null कर देता है।
eventTypesWebhookEvent[] | ['*']- सदस्यता लिए गए events, या `['*']` जब endpoint ने किसी का नाम नहीं लिया। `['*']` वह तरीका है जिससे खाली संग्रहीत सूची read पर दिखाई जाती है और उसे वापस भेजा नहीं जा सकता, और वह पूरे कैटलॉग के बजाय तेरह संदेश events का प्रतीक है। `create` और `update` केवल शाब्दिक event नाम स्वीकार करते हैं।
enabledboolean- क्या deliveries की कोशिश की जाती है; निष्क्रिय endpoint को events भेजते समय छोड़ दिया जाता है और उसका secret तथा उसका delivery इतिहास बना रहता है। यहाँ हमेशा true, क्योंकि `WebhookCreate` में `enabled` है ही नहीं और केवल `WebhookPatch` में है।
lastDeliveryAtstring | null- आखिरी delivery कोशिश का ISO 8601 timestamp, आखिरी सफलता का नहीं। यह विफल POST के बाद भी लगाया जाता है, इसलिए यह बताता है कि endpoint को आज़माया गया और `listDeliveries` बताता है कि क्या हुआ। पहली कोशिश तक null, इसलिए `create` पर हमेशा null।
createdAtstring- endpoint कब पंजीकृत हुआ, इसका ISO 8601 timestamp। `list` इसी फ़ील्ड के अनुसार सबसे नए endpoint पहले लौटाता है।
secretstring- वह HMAC-SHA-256 key जो हर delivery के `X-OpenEmail-Signature` पर हस्ताक्षर करती है: `whsec_` के बाद base64url में 32 यादृच्छिक बाइट, और वही जो आप `verifyWebhookSignature` को देते हैं। इसे `create` और `rotateSecret` लौटाते हैं, और कुछ नहीं। कोई read इसे कभी नहीं दोहराता, इसलिए इसे अभी संग्रहीत करें; खोया हुआ secret केवल `rotateSecret` से बदला जा सकता है, जो पुराने को तुरंत रद्द कर देता है।