وب‌هوک‌ها: دریافت خودکار نتیجه

به‌جای polling، نتیجهٔ تسک‌های عکس و ویدیوی ساخته‌شده با API به‌محض پایان با یک POST امضاشده به نشانی HTTPS شما ارسال می‌شود. ثبت نشانی: https://api.bananaai.ir/console#webhooks (حداکثر ۵ نشانی). کلید امضای whsec_… فقط یک بار نمایش داده می‌شود.

رویدادها

• task.completed: تسک موفق؛ خروجی‌ها در data.images / data.videos
• task.failed: تسک ناموفق؛ علت در data.error، اعتبار برگشته
• wallet.low_balance: موجودی کیف پول از آستانهٔ هشدار پایین‌تر رفت (تنظیم در https://api.bananaai.ir/console#alerts)؛ data شامل credits، threshold، topup_url و auto_topup (بستهٔ شارژ سریع یا null) است. این رویداد taskId ندارد.
• webhook.test: فقط از دکمهٔ «ارسال آزمایشی» پنل

بدنه

{
  "id": "evt_4mZ0q9sJ2bN7xY1vT8cK3pLd",
  "type": "task.completed",
  "created_at": "2026-09-27T10:21:07.000Z",
  "data": {
    "id": "task_abc123",
    "status": "completed",
    "type": "image",
    "model": "nano-banana-2",
    "images": ["https://cdn.bananaai.ir/.../output.png"],
    "videos": [],
    "error": null,
    "credits_reserved": 8,
    "credits_deducted": true,
    "metadata": { "order_id": "1042" },
    "created_at": "2026-09-27T10:20:41.000Z",
    "completed_at": "2026-09-27T10:21:07.000Z"
  }
}

هدرها

• BananaAI-Signature: t=<unix>,v1=<hex> که v1 = HMAC-SHA256(secret, ${t}.${rawBody})
• BananaAI-Event: نوع رویداد
• BananaAI-Delivery: شناسهٔ یکتای ارسال (در تلاش مجدد ثابت؛ برای حذف تکراری)
• BananaAI-Timestamp: همان t

بررسی امضا (Node.js)

const { t, v1 } = Object.fromEntries(sigHeader.split(",").map((p) => p.split("=")));
const expected = crypto.createHmac("sha256", SECRET).update(`${t}.${rawBody}`).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) &&
  Math.abs(Date.now() / 1000 - Number(t)) < 300;

پاسخ و تلاش مجدد

• پاسخ 2xx در کمتر از ۱۰ ثانیه = موفق. ریدایرکت دنبال نمی‌شود.
• ناموفق‌ها تا ۶ بار ارسال می‌شوند: پس از ۱ دقیقه، ۵ دقیقه، ۳۰ دقیقه، ۲ ساعت، ۸ ساعت.
• ترتیب تضمین نمی‌شود و تکرار ممکن است؛ با BananaAI-Delivery تکراری‌ها را کنار بگذارید.
• پس از ۲۵ شکست پیاپی، وب‌هوک خودکار غیرفعال می‌شود.
• فقط https عمومی؛ IP خصوصی مسدود است.