# وب‌هوک‌ها


به‌جای 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`: فقط از دکمهٔ «ارسال آزمایشی» پنل

## بدنه

```json
{
  "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)

```javascript
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 خصوصی مسدود است.