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 document: 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 ঘণ্টা ধরে ক্রমবর্ধমান বিরতিতে আবার চেষ্টা করা হয়; তারপর ডেলিভারিটি ডেড লেটার হয়, 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 সহ, অন্য সবগুলোর মতোই স্বাক্ষরিত, এবং আপনি যে ইভেন্টই বেছে নিন না কেন পাঠানো হয়। মিনিটে সর্বোচ্চ একবার।