ZeeDo API

सेटिंग्स → API और वेबहुक में एक कुंजी बनाएँ (पहले एक मालिक पुष्टि करता है कि यह वही है), फिर उसे bearer token के रूप में लेकर API को कॉल करें। बेस URL https://api.zeedo.cloud/v1 है।

curl https://api.zeedo.cloud/v1/me \
  -H "Authorization: Bearer <आपकी API कुंजी>"

• कुंजियाँ संगठन की होती हैं, उनका एक दायरा होता है — read, write या admin — और उन्हें एक ही वर्कस्पेस तक सीमित रखा जा सकता है।
• JSON बॉडी, snake_case फ़ील्ड, समय ISO 8601 UTC में।
• त्रुटियाँ RFC 9457 problem दस्तावेज़ होती हैं: type, title, status, detail और, अस्वीकार हुए फ़ील्ड के लिए, JSON pointer के साथ errors[]।
• सूचियाँ limit (ज़्यादा से ज़्यादा 200) और next_cursor से पन्नों में आती हैं।
• हर POST के साथ Idempotency-Key हेडर भेजें: 24 घंटे के भीतर दोहराई गई कॉल वही जवाब देती है जो पहली ने दिया था।
• हर कुंजी पर एक मिनट में 600 अनुरोध और 10 खुली स्ट्रीम, RateLimit-* हेडर के साथ।

एक संगठन एक एंडपॉइंट दर्ज करता है (सेटिंग्स → API और वेबहुक, या POST /webhooks) और अपने इवेंट चुनता है। हर इवेंट JSON का एक POST होता है जिसमें id, प्रकार और टाइमस्टैम्प होते हैं — किसी व्यक्ति का नाम, ईमेल या IP पता कभी नहीं, जिन्हें आप कुंजी से API के ज़रिए पढ़ सकते हैं।

{
  "id": "evt_eu_01J9ZQ3M7X5V2K8R4T6Y1N0PBA",
  "type": "run.completed",
  "version": 1,
  "occurred_at": "2026-09-27T10:02:31.000Z",
  "org_id": "org_eu_01J9ZQ1C4H8D6F2W5S7K3M9QXE",
  "data": {
    "run_id": "run_eu_01J9ZQ2V8N4B6C1X3Z5Q7W9ERT",
    "bot_id": "bot_eu_01J9ZQ2A3S5D7F9G1H3J5K7L9M"
  }
}

हर डिलीवरी हस्ताक्षरित होती है: ZeeDo-Signature: t=<unix सेकंड>,v1=<हस्ताक्षर>, जहाँ हस्ताक्षर <t>.<मूल बॉडी> का hex HMAC-SHA256 है, जिसकी कुंजी आपके एंडपॉइंट का सीक्रेट है। सीक्रेट बदलने के बाद पिछला सीक्रेट 24 घंटे तक दूसरे v1 के रूप में साथ में हस्ताक्षर करता है। 5 मिनट से पुराना हस्ताक्षर अस्वीकार करें।

import { createHmac, timingSafeEqual } from 'node:crypto';

// header: ZeeDo-Signature का मान; body: अनुरोध की मूल बॉडी, किसी भी JSON पार्सिंग से पहले
export function verified(header, body, secret) {
  const parts = header.split(',');
  const t = parts.find((p) => p.startsWith('t='))?.slice(2);
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
  return parts.filter((p) => p.startsWith('v1=')).some((p) =>
    p.length === expected.length + 3 && timingSafeEqual(Buffer.from(p.slice(3)), Buffer.from(expected)));
}

• 10 सेकंड के भीतर कोई भी 2xx जवाब दें। बाक़ी कुछ भी — त्रुटि, रीडायरेक्ट, कोई जवाब नहीं — 24 घंटे तक बढ़ते अंतराल पर दोबारा भेजा जाता है; उसके बाद डिलीवरी dead letter बन जाती है, 7 दिन रखी जाती है और सेटिंग्स से फिर भेजी जा सकती है।
• डिलीवरी कम से कम एक बार होती है और किसी तय क्रम में नहीं: जो id आप पहले संभाल चुके हैं, उसे छोड़ दें।
• अनुरोधों में ZeeDo-Event-Id, ZeeDo-Event-Type और ZeeDo-Delivery-Id भी होते हैं। एंडपॉइंट किसी सार्वजनिक होस्ट नाम पर पोर्ट 443 पर https होने चाहिए।
• इवेंट: alert.fired, approval.decided, approval.requested, billing.service_state_changed, bot.state_changed, budget.threshold, connection.created, connection.error, consent.recorded, memory.note_created, policy.updated, run.cancelled, run.completed, run.failed, run.parked, task.completed, और task.created।
• अपना एंडपॉइंट जाँचने के लिए सेटिंग्स → API और वेबहुक में “टेस्ट भेजें” दबाएँ: webhook.test प्रकार की एक डिलीवरी, खाली data के साथ, बाक़ी सबकी तरह साइन की हुई, आपने जो भी इवेंट चुने हों, भेजी जाती है। एक मिनट में अधिकतम एक बार।