मुख्य कंटेंट पर जाएँ
Sursa Developers

POST/v1/webhooks

वेबहुक बनाएँ

create_webhook

URL में https होना चाहिए, और उसका होस्ट पब्लिक पतों पर रिज़ॉल्व होना चाहिए। निजी (RFC 1918), loopback, link-local, क्लाउड मेटाडेटा और दूसरे ख़ास उद्देश्य वाले नेटवर्क रजिस्ट्रेशन पर भी और हर कनेक्शन पर भी अस्वीकार किए जाते हैं। साइनिंग सीक्रेट रिस्पॉन्स में एक बार दिखाया जाता है (secret); उसके बाद उसे सिर्फ़ रोटेट किया जा सकता है। एक संगठन में ज़्यादा से ज़्यादा 20 वेबहुक हो सकते हैं।

सब्सक्रिप्शन में इवेंट टाइप और डोमेन मास्क (card.*, *) होते हैं। ऐक्सेस API कुंजी की तरह ही सेट होता है: role, data_profile_id और collection_ids। जिस ऑब्जेक्ट को रोल, डेटा प्रोफ़ाइल या कलेक्शन नहीं देख सकते, उसके बारे में इवेंट डिलीवर नहीं होता। tags कार्ड के इवेंट को उन कार्ड तक सीमित करते हैं, जिनमें इनमें से कोई टैग है। payload: thin इवेंट data के बिना भेजता है। कस्टम हेडर (headers) और बाहर जाने वाला ऑथराइज़ेशन (auth) एन्क्रिप्ट करके रखे जाते हैं; रिस्पॉन्स में सिर्फ़ हेडर के नाम और value_set और auth_set फ़्लैग होते हैं।

ऑथेंटिकेशन

Authorization हेडर में API कुंजी भेजें: Authorization: Bearer <कुंजी>।

हेडर पैरामीटर

  • Idempotency-Keystring

    लिखने वाली रिक्वेस्ट के सुरक्षित रीट्राई के लिए कुंजी: 1 से 255 प्रिंट होने वाले ASCII कैरेक्टर; हर लॉजिकल ऑपरेशन के लिए एक UUID v4 की सलाह दी जाती है। उसी कुंजी के साथ 24 घंटे के अंदर रीट्राई ऑपरेशन को दोबारा नहीं चलाता: वह सेव किया गया रिस्पॉन्स (स्टेटस, हेडर और बॉडी) Idempotency-Replayed: true हेडर के साथ लौटाता है। वही कुंजी, पर अलग मेथड, पाथ, Content-Type या बॉडी हो, तो 409 api.idempotency_mismatch लौटता है; जब तक पहली रिक्वेस्ट चल रही है, तब तक 409 api.idempotency_in_progress और Retry-After: 1। 5xx या 429 रिस्पॉन्स के बाद कुंजी छोड़ दी जाती है, और रीट्राई ऑपरेशन को फिर से चलाता है। कुंजी संगठन और कॉल करने वाले (API कुंजी, यूज़र या कस्टम स्रोत की कुंजी) के दायरे में होती है।

    length ≥ 1, length ≤ 255

रिक्वेस्ट बॉडी

application/json

ऑब्जेक्ट: WebhookCreate

  • urlstringज़रूरी

    प्राप्तकर्ता का URL, सिर्फ़ https://, 2048 अक्षरों तक।

    length ≤ 2048

  • descriptionstring

    length ≤ 200

  • eventsarray of WebhookEventFilterज़रूरी

    items ≥ 1

  • roleWebhookRole
  • data_profile_idinteger | null
  • collection_idsarray of integer

    वे कलेक्शन, जिनके बारे में वेबहुक को इवेंट मिलते हैं। मान न हो या सूची ख़ाली हो, तो रोल और डेटा प्रोफ़ाइल के लिए उपलब्ध सभी कलेक्शन। जो कुंजी ख़ुद कलेक्शन तक सीमित है, वह सिर्फ़ अपने कलेक्शन की ग़ैर-ख़ाली सूची के साथ वेबहुक बनाती है। इस फ़ील्ड के बिना, ख़ाली सूची के साथ या उसकी सूची से बाहर के कलेक्शन के साथ रिक्वेस्ट 403 webhooks.collections_outside_key लौटाती है।

    items ≤ 200

  • tagsarray of string

    items ≤ 50

  • payloadWebhookPayloadMode
  • headersarray of WebhookHeaderInput

    items ≤ 10

  • authWebhookAuthInput

रिस्पॉन्स

201बनाया गया। सिर्फ़ इसी बार `secret` दिखाया जाता है।

रिस्पॉन्स हेडर

  • RateLimit-Policy

    लागू सीमाएँ, IETF ड्राफ़्ट draft-ietf-httpapi-ratelimit-headers के फ़ॉर्मेट में: कॉमा से अलग आइटम "<name>";q=<quota>;w=<window in seconds>। key API कुंजी की रिक्वेस्ट दर है (कोटा बर्स्ट है, विंडो उसके पूरी तरह भरने का समय है; सेशन के लिए यह user है, बिना क्रेडेंशियल के ip); minute, day और month UTC में कैलेंडर मिनट, दिन और महीने के लिए संगठन के कोटा हैं।

  • RateLimit

    RateLimit-Policy की हर सीमा में से कितना बचा है: "<name>";r=<remaining>;t=<seconds until reset>।

  • X-RateLimit-Limit

    RateLimit-Policy की सबसे सख़्त एंट्री की सीमा (जिसमें सबसे कम रिक्वेस्ट बची हैं)।

  • X-RateLimit-Remaining

    सबसे सख़्त सीमा में बची रिक्वेस्ट।

  • X-RateLimit-Reset

    सबसे सख़्त सीमा के रीसेट होने तक के सेकंड।

  • Idempotency-Replayed

    true का मतलब है कि रिस्पॉन्स इस Idempotency-Key के लिए सेव किए गए रिस्पॉन्स से दोहराया गया: ऑपरेशन दोबारा नहीं चला।

application/json

ऑब्जेक्ट: WebhookCreated

  • idintegerज़रूरी
  • urlstringज़रूरी
  • descriptionstringज़रूरी
  • eventsarray of WebhookEventFilterज़रूरी
  • activebooleanज़रूरी
  • statusWebhookStatusज़रूरी
  • paused_atstring (date-time) | null
  • paused_reasonstring | null

    failures: लगातार 10 असफल प्रयास; feature_disabled: प्लान में वेबहुक शामिल नहीं हैं।

  • disabled_reasonstring | null

    gone: प्राप्तकर्ता ने 410 से जवाब दिया; manual: एडमिन ने बंद किया।

    मान्य मान: gonemanualnull

  • disabled_atstring (date-time) | null
  • roleWebhookRoleज़रूरी
  • data_profile_idinteger | null

    वेबहुक की डेटा प्रोफ़ाइल (null का मतलब है कोई प्रोफ़ाइल नहीं, जैसे उसी रोल वाली API कुंजी के लिए)।

  • collection_idsarray of integerज़रूरी

    वे कलेक्शन, जिनके बारे में वेबहुक इवेंट पाता है; ख़ाली का मतलब है रोल और डेटा प्रोफ़ाइल को उपलब्ध सभी कलेक्शन।

  • tagsarray of stringज़रूरी

    कार्ड के इवेंट सिर्फ़ उन कार्ड के लिए, जिन पर इनमें से कोई टैग हो; ख़ाली का मतलब है कोई फ़िल्टर नहीं।

  • payloadWebhookPayloadModeज़रूरी
  • headersarray of WebhookHeaderज़रूरी
  • auth_typestring | null

    बाहर जाने वाली रिक्वेस्ट के ऑथराइज़ेशन का टाइप (null का मतलब है कोई नहीं)।

    मान्य मान: bearerbasicnull

  • auth_setbooleanज़रूरी

    क्या बाहर जाने वाली रिक्वेस्ट का ऑथराइज़ेशन सेट है (मान कभी नहीं लौटाए जाते)।

  • previous_secret_valid_untilstring (date-time) | null

    कब तक डिलीवरी पिछले सीक्रेट से भी साइन की जाती हैं (null का मतलब है कोई ओवरलैप अवधि नहीं)।

  • healthWebhookHealth
  • consecutive_failuresintegerज़रूरी
  • last_delivery_atstring (date-time) | null
  • last_success_atstring (date-time) | null
  • last_errorstring | null
  • created_byinteger | null
  • created_by_namestring | null
  • created_atstring (date-time)ज़रूरी
  • updated_atstring (date-time)ज़रूरी
  • secretstringज़रूरी

    whsec_ और उसके बाद base64 में 32 बाइट (नए सीक्रेट पैडिंग के साथ स्टैंडर्ड वर्णमाला इस्तेमाल करते हैं, पुराने base64url)। इसे प्राप्तकर्ता की तरफ़ सेव करें; यह API के रिस्पॉन्स में फिर कभी नहीं दिखता। Standard Webhooks की साइनिंग कुंजी whsec_ के बाद वाले हिस्से का base64 डिकोड है।

  • previous_valid_untilstring (date-time) | null

    रोटेशन के बाद पिछला सीक्रेट कब तक स्वीकार होता है। बनाते समय null।

400रिक्वेस्ट अमान्य है: पैरामीटर का मान या ऑब्जेक्ट की स्थिति यह कार्रवाई करने नहीं देती (`detail` एक संदेश है)।

रिस्पॉन्स हेडर

  • RateLimit-Policy

    लागू सीमाएँ, IETF ड्राफ़्ट draft-ietf-httpapi-ratelimit-headers के फ़ॉर्मेट में: कॉमा से अलग आइटम "<name>";q=<quota>;w=<window in seconds>। key API कुंजी की रिक्वेस्ट दर है (कोटा बर्स्ट है, विंडो उसके पूरी तरह भरने का समय है; सेशन के लिए यह user है, बिना क्रेडेंशियल के ip); minute, day और month UTC में कैलेंडर मिनट, दिन और महीने के लिए संगठन के कोटा हैं।

  • RateLimit

    RateLimit-Policy की हर सीमा में से कितना बचा है: "<name>";r=<remaining>;t=<seconds until reset>।

  • X-RateLimit-Limit

    RateLimit-Policy की सबसे सख़्त एंट्री की सीमा (जिसमें सबसे कम रिक्वेस्ट बची हैं)।

  • X-RateLimit-Remaining

    सबसे सख़्त सीमा में बची रिक्वेस्ट।

  • X-RateLimit-Reset

    सबसे सख़्त सीमा के रीसेट होने तक के सेकंड।

application/json

ऑब्जेक्ट: Error

401कोई क्रेडेंशियल नहीं भेजा गया (न सेशन कुकी, न API कुंजी), या कुंजी नहीं मिली।

रिस्पॉन्स हेडर

  • RateLimit-Policy

    लागू सीमाएँ, IETF ड्राफ़्ट draft-ietf-httpapi-ratelimit-headers के फ़ॉर्मेट में: कॉमा से अलग आइटम "<name>";q=<quota>;w=<window in seconds>। key API कुंजी की रिक्वेस्ट दर है (कोटा बर्स्ट है, विंडो उसके पूरी तरह भरने का समय है; सेशन के लिए यह user है, बिना क्रेडेंशियल के ip); minute, day और month UTC में कैलेंडर मिनट, दिन और महीने के लिए संगठन के कोटा हैं।

  • RateLimit

    RateLimit-Policy की हर सीमा में से कितना बचा है: "<name>";r=<remaining>;t=<seconds until reset>।

  • X-RateLimit-Limit

    RateLimit-Policy की सबसे सख़्त एंट्री की सीमा (जिसमें सबसे कम रिक्वेस्ट बची हैं)।

  • X-RateLimit-Remaining

    सबसे सख़्त सीमा में बची रिक्वेस्ट।

  • X-RateLimit-Reset

    सबसे सख़्त सीमा के रीसेट होने तक के सेकंड।

application/json

ऑब्जेक्ट: Error

403कार्रवाई की अनुमति नहीं है: रोल काफ़ी नहीं है, कलेक्शन या कार्ड तक ऐक्सेस नहीं है, रिक्वेस्ट “View as” मोड में चल रही है, या संगठन निलंबित है या हटा दिया गया है (`detail` एक ऑब्जेक्ट है, जिसमें `code: org_suspended | org_deleted` है)।

रिस्पॉन्स हेडर

  • RateLimit-Policy

    लागू सीमाएँ, IETF ड्राफ़्ट draft-ietf-httpapi-ratelimit-headers के फ़ॉर्मेट में: कॉमा से अलग आइटम "<name>";q=<quota>;w=<window in seconds>। key API कुंजी की रिक्वेस्ट दर है (कोटा बर्स्ट है, विंडो उसके पूरी तरह भरने का समय है; सेशन के लिए यह user है, बिना क्रेडेंशियल के ip); minute, day और month UTC में कैलेंडर मिनट, दिन और महीने के लिए संगठन के कोटा हैं।

  • RateLimit

    RateLimit-Policy की हर सीमा में से कितना बचा है: "<name>";r=<remaining>;t=<seconds until reset>।

  • X-RateLimit-Limit

    RateLimit-Policy की सबसे सख़्त एंट्री की सीमा (जिसमें सबसे कम रिक्वेस्ट बची हैं)।

  • X-RateLimit-Remaining

    सबसे सख़्त सीमा में बची रिक्वेस्ट।

  • X-RateLimit-Reset

    सबसे सख़्त सीमा के रीसेट होने तक के सेकंड।

application/json

ऑब्जेक्ट: Error

409ऑब्जेक्ट की स्थिति यह कार्रवाई करने नहीं देती, जैसे डुप्लिकेट, चल रही इंडेक्सिंग या पहले से प्रोसेस हो चुका जॉब।

रिस्पॉन्स हेडर

  • RateLimit-Policy

    लागू सीमाएँ, IETF ड्राफ़्ट draft-ietf-httpapi-ratelimit-headers के फ़ॉर्मेट में: कॉमा से अलग आइटम "<name>";q=<quota>;w=<window in seconds>। key API कुंजी की रिक्वेस्ट दर है (कोटा बर्स्ट है, विंडो उसके पूरी तरह भरने का समय है; सेशन के लिए यह user है, बिना क्रेडेंशियल के ip); minute, day और month UTC में कैलेंडर मिनट, दिन और महीने के लिए संगठन के कोटा हैं।

  • RateLimit

    RateLimit-Policy की हर सीमा में से कितना बचा है: "<name>";r=<remaining>;t=<seconds until reset>।

  • X-RateLimit-Limit

    RateLimit-Policy की सबसे सख़्त एंट्री की सीमा (जिसमें सबसे कम रिक्वेस्ट बची हैं)।

  • X-RateLimit-Remaining

    सबसे सख़्त सीमा में बची रिक्वेस्ट।

  • X-RateLimit-Reset

    सबसे सख़्त सीमा के रीसेट होने तक के सेकंड।

application/json

ऑब्जेक्ट: Error

422वैलिडेशन एरर: बॉडी या पैरामीटर स्कीमा से मेल नहीं खाते (`detail` वैलिडेशन एरर की सूची है), या पैरामीटर का मान सीमा से बाहर है (`detail` एक संदेश है)।

रिस्पॉन्स हेडर

  • RateLimit-Policy

    लागू सीमाएँ, IETF ड्राफ़्ट draft-ietf-httpapi-ratelimit-headers के फ़ॉर्मेट में: कॉमा से अलग आइटम "<name>";q=<quota>;w=<window in seconds>। key API कुंजी की रिक्वेस्ट दर है (कोटा बर्स्ट है, विंडो उसके पूरी तरह भरने का समय है; सेशन के लिए यह user है, बिना क्रेडेंशियल के ip); minute, day और month UTC में कैलेंडर मिनट, दिन और महीने के लिए संगठन के कोटा हैं।

  • RateLimit

    RateLimit-Policy की हर सीमा में से कितना बचा है: "<name>";r=<remaining>;t=<seconds until reset>।

  • X-RateLimit-Limit

    RateLimit-Policy की सबसे सख़्त एंट्री की सीमा (जिसमें सबसे कम रिक्वेस्ट बची हैं)।

  • X-RateLimit-Remaining

    सबसे सख़्त सीमा में बची रिक्वेस्ट।

  • X-RateLimit-Reset

    सबसे सख़्त सीमा के रीसेट होने तक के सेकंड।

application/json

ऑब्जेक्ट: Error

429बहुत ज़्यादा रिक्वेस्ट (`api.rate_limited`), संगठन का मिनट, दिन या महीने का कोटा ख़त्म हो गया है (`api.quota_exceeded`; `error.details` में `quota`, `limit` और `reset_at` होते हैं), संगठन की सीमा पूरी हो गई है, या जवाब देने वाली सर्विस व्यस्त है (`answers.engine_busy`)। `Retry-After` हेडर में दिए गए समय तक इंतज़ार करें।

रिस्पॉन्स हेडर

  • Retry-After

    रिक्वेस्ट का रीट्राई करने से पहले कितने सेकंड इंतज़ार करना है।

  • RateLimit-Policy

    लागू सीमाएँ, IETF ड्राफ़्ट draft-ietf-httpapi-ratelimit-headers के फ़ॉर्मेट में: कॉमा से अलग आइटम "<name>";q=<quota>;w=<window in seconds>। key API कुंजी की रिक्वेस्ट दर है (कोटा बर्स्ट है, विंडो उसके पूरी तरह भरने का समय है; सेशन के लिए यह user है, बिना क्रेडेंशियल के ip); minute, day और month UTC में कैलेंडर मिनट, दिन और महीने के लिए संगठन के कोटा हैं।

  • RateLimit

    RateLimit-Policy की हर सीमा में से कितना बचा है: "<name>";r=<remaining>;t=<seconds until reset>।

  • X-RateLimit-Limit

    RateLimit-Policy की सबसे सख़्त एंट्री की सीमा (जिसमें सबसे कम रिक्वेस्ट बची हैं)।

  • X-RateLimit-Remaining

    सबसे सख़्त सीमा में बची रिक्वेस्ट।

  • X-RateLimit-Reset

    सबसे सख़्त सीमा के रीसेट होने तक के सेकंड।

application/json

ऑब्जेक्ट: Error

एरर कोड

हर रिक्वेस्ट के सामान्य कोड के अलावा वे कोड, जो यह एंडपॉइंट एरर होने पर error.code में लौटा सकता है।

सुरक्षित रीट्राई

हर POST और PATCH के साथ Idempotency-Key हेडर भेजें (उदाहरण के लिए, UUID)। 24 घंटे के अंदर उसी कुंजी के साथ रीट्राई करने पर रिक्वेस्ट दोबारा नहीं चलती, बल्कि सेव किया गया रिस्पॉन्स लौटता है।

रेट लिमिट

रिस्पॉन्स में RateLimit और RateLimit-Policy हेडर होते हैं, और पहले वाले X-RateLimit-Limit, X-RateLimit-Remaining और X-RateLimit-Reset भी। 429 रिस्पॉन्स में Retry-After सेकंड में होता है: उतना इंतज़ार करें और रीट्राई करें।

← webhooks · API रेफ़रेंस