وبهوک ها: رویداد ها

قالب کلی

{
  "event": "otp.attempt.sent",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "attempt": 1,
  "created_at": "2026-05-24T10:30:00.000000+00:00",
  "data": {}
}

event_id برای تلاش های دوباره همان event ثابت می ماند و به عنوان کلید idempotency سمت محصول مناسب است.

otp.attempt.sent

{
  "event": "otp.attempt.sent",
  "data": {
    "verification_id": "550e8400-e29b-41d4-a716-446655440000",
    "phone": "+989123456789",
    "channel": "eitaa",
    "current_channel": {"type": "messenger", "provider": "eitaa", "credential_id": 21, "label": "Eitaa main"},
    "sequence": 1,
    "status": "sent"
  }
}

otp.attempt.failed

{
  "event": "otp.attempt.failed",
  "data": {
    "verification_id": "550e8400-e29b-41d4-a716-446655440000",
    "phone": "+989123456789",
    "channel": "sms",
    "current_channel": {"type": "sms", "provider": "smsir", "credential_id": 12, "label": "Primary sms.ir"},
    "sequence": 2,
    "status": "failed",
    "error": "gateway_timeout"
  }
}

otp.verified

وقتی کد درست تایید شود ارسال می شود. این رویداد برای بستن موفق فرایند و ادامه مسیر محصول مناسب است.

{
  "event": "otp.verified",
  "data": {
    "verification_id": "550e8400-e29b-41d4-a716-446655440000",
    "phone": "+989123456789",
    "channel": "eitaa",
    "current_channel": {"type": "messenger", "provider": "eitaa", "credential_id": 21, "label": "Eitaa main"},
    "status": "verified"
  }
}

otp.failed

وقتی هیچ کانالی نتواند کد را تحویل دهد ارسال می شود. این حالت با کد اشتباه کاربر فرق دارد؛ موضوع این است که مسیرهای ارسال به نتیجه نرسیده اند.

{
  "event": "otp.failed",
  "data": {
    "verification_id": "550e8400-e29b-41d4-a716-446655440005",
    "phone": "+989123456789",
    "status": "failed",
    "reason": "all_channels_exhausted"
  }
}

otp.expired

وقتی زمان اعتبار verification تمام شود و کاربر تایید نشده باشد ارسال می شود. بعد از این رویداد، همان کد دیگر قابل قبول نیست.

{
  "event": "otp.expired",
  "data": {
    "verification_id": "550e8400-e29b-41d4-a716-446655440006",
    "phone": "+989123456789",
    "status": "expired"
  }
}

otp.locked

بعد از تعداد زیاد تلاش اشتباه، verification قفل می شود و این رویداد ارسال می شود. در این حالت همان verification دوباره قابل استفاده نیست.

{
  "event": "otp.locked",
  "data": {
    "verification_id": "550e8400-e29b-41d4-a716-446655440007",
    "phone": "+989123456789",
    "status": "locked"
  }
}

test.ping

رویداد آزمایشی دکمه تست داشبورد است. برای اطمینان از رسیدن درخواست، بررسی امضا و پاسخ ۲xx استفاده می شود. verification_id در این رویداد null است.

{
  "event": "test.ping",
  "event_id": "a7b8c9d0-e1f2-3456-abcd-567890123456",
  "verification_id": null,
  "attempt": 1,
  "created_at": "2026-05-24T10:00:00.000000+00:00"
}