قرارداد وب‌هوک تحویل لیاد

لیاد یادآور را زمان‌بندی می‌کند و برای هر کانال یک درخواست یکسان به وب‌هوک شما می‌فرستد.

اصل

آداپتر پیش‌فرض لیاد: tenant_webhook
بدنه JSON برای هر چهار کانال یکسان است
کانال هم در مسیر URL شما، هم در فیلد channel، هم در هدر X-Liad-Channel می‌آید
پاسخ HTTP 2xx = تحویل موفق. غیر از آن = شکست

Don’t want a webhook? Use Simple Messages (POST /v1/messages — Liad sends SMS on managed rails.

نمونه URLهای پایدار

کانال	Method	URL
sms	`POST`	`https://liom.app/liad-hooks/v1/sms`
telegram	`POST`	`https://liom.app/liad-hooks/v1/telegram`
bale	`POST`	`https://liom.app/liad-hooks/v1/bale`
whatsapp	`POST`	`https://liom.app/liad-hooks/v1/whatsapp`
eitaa	`POST`	`https://liom.app/liad-hooks/v1/eitaa`
rubika	`POST`	`https://liom.app/liad-hooks/v1/rubika`

سرویس‌گیرنده باید URLهای خودش را در پنل ثبت کند.

بدنه درخواست (ثابت)

{
  "event": "liad.delivery.request",
  "version": 1,
  "deliveryAttemptId": "uuid",
  "fireEventId": "uuid",
  "reminderId": "uuid",
  "tenantId": "uuid",
  "channel": "sms|telegram|bale|whatsapp|eitaa|rubika",
  "kind": "main|pre",
  "externalUserId": "your-user-id",
  "title": "reminder title",
  "body": "short sendable text",
  "recipient": {
    "endpoint": "fcm-token | chat-id (optional)",
    "phone": "+15551234567",
    "telegramId": "123456789",
    "baleId": "123456789"
  },
  "sentAt": "2026-08-07T12:00:00Z"
}

title = عنوان · body = متن کوتاه ارسال‌شونده

گیرنده بر اساس کانال

کانال	الزامی	یادداشت
sms	`recipient.phone` / `endpoint`	شماره موبایل
telegram	`recipient.telegramId` / `endpoint`	چت‌آیدی تلگرام
bale	`recipient.phone` / `baleId`	موبایل یا چت‌آیدی بله
whatsapp	`recipient.phone` / `endpoint`	شماره موبایل
eitaa	`recipient.phone` / `endpoint`	شماره موبایل
rubika	`recipient.phone` / `endpoint`	شماره موبایل

هدرها

هدر	الزامی	معنی
`Content-Type`	بله	`application/json`
`X-Liad-Signature`	توصیه می‌شود	sha256= + HMAC-SHA256
`X-Liad-Delivery-Attempt-Id`	اختیاری	شناسه تلاش تحویل
`X-Liad-Channel`	اختیاری	نام کانال
`X-Liad-Tenant-Id`	اختیاری	شناسه مستأجر

پاسخ موفق (2xx)

{
  "ok": true,
  "providerRef": "string-or-null",
  "channel": "sms"
}

پاسخ خطا (4xx / 5xx)

{
  "ok": false,
  "error": "missing_recipient",
  "detail": "…"
}

لیاد فقط وضعیت HTTP را برای صورتحساب موفق می‌خواند.

تنظیم در پنل

در پنل ادمین → مستأجر → تب وب‌هوک تحویل برای هر کانال:

آدرس وب‌هوک HTTPS
رمز امضا (HMAC) — اختیاری ولی توصیه‌شده
فعال / غیرفعال

API: PUT /v1/admin/tenants/{id}/channels/{channel}