وب‌هوک‌ها

وب‌هوک‌ها رویدادها را همان لحظه‌ای که رخ می‌دهند به سرور شما می‌فرستند، پس لازم نیست پرس‌وجو کنید. هر وب‌هوک متعلق به یک کلید API است. رویدادهای شماره‌هایی را که با آن کلید خریده شده‌اند، به‌علاوه هشدارهای کم شدن موجودی حساب شما، دریافت می‌کند.

رویدادها

ساخت وب‌هوک

در حساب > توسعه‌دهندگان یک کلید را باز کنید و وب‌هوکی با نشانی، رویدادهای مورد نظر و توضیح اختیاری اضافه کنید. هر کلید می‌تواند تا ۳ وب‌هوک داشته باشد.

نشانی باید:

• با https:// شروع شود؛
• از نام میزبان استفاده کند، نه نشانی IP؛
• به نشانی عمومی برسد. شبکه‌های خصوصی، localhost و بازه‌های مشابه رد می‌شوند.

یک راز امضا دریافت می‌کنید که با whsec_ شروع می‌شود. مثل کلید API، فقط یک بار نمایش داده می‌شود. می‌توانید بعداً آن را عوض کنید که این هم گذرواژه می‌خواهد.

شکل یک ارسال

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: SmsGrab-Webhooks/1.0
SmsGrab-Event: activation.code_received
SmsGrab-Delivery: 9f7d6c1e-2b44-4c1a-8f0e-6a3d2c1b0e9f
SmsGrab-Signature: t=1790503200,v1=3b9a0c…

{ "id": "evt_4e1f…", "type": "activation.code_received", "created_at": "2026-09-27T10:06:12.004Z",
  "api_version": "2026-09-27", "data": { "activation": { "id": "5c1d0c2e-…", "status": "CODE_RECEIVED" } } }

بررسی امضا

SmsGrab-Signature یک مهر زمانی t و v1 دارد که HMAC-SHA256 از t، یک نقطه و بدنه خام درخواست با کلید راز شماست. ارسال‌هایی را که مهر زمانی‌شان بیش از ۳۰۰ ثانیه با ساعت شما فاصله دارد رد کنید و امضاها را در زمان ثابت مقایسه کنید.

[$t, $v1] = (function (string $h): array {
    parse_str(str_replace(',', '&', $h), $p);
    return [(int) ($p['t'] ?? 0), (string) ($p['v1'] ?? '')];
})($_SERVER['HTTP_SMSGRAB_SIGNATURE'] ?? '');
$body = file_get_contents('php://input');
$expected = hash_hmac('sha256', $t.'.'.$body, getenv('SMSGRAB_WEBHOOK_SECRET'));
$ok = abs(time() - $t) <= 300 && hash_equals($expected, $v1);

import hmac, hashlib, time

def verify(header: str, body: bytes, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", "0"))
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return abs(time.time() - t) <= 300 and hmac.compare_digest(expected, parts.get("v1", ""))

import crypto from 'node:crypto';

export function verify(header, rawBody, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const t = Number(parts.t ?? 0);
  const expected = crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex');
  const given = Buffer.from(parts.v1 ?? '', 'utf8');
  return Math.abs(Date.now() / 1000 - t) <= 300 && given.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(expected, 'utf8'), given);
}

همیشه بدنه خام را دقیقاً همان‌طور که دریافت کرده‌اید، پیش از تجزیه JSON، بررسی کنید.

سریع پاسخ دهید

ظرف ۱۰ ثانیه با هر وضعیت 2xx پاسخ دهید و کارهای کند را بعداً، مثلاً در صف، انجام دهید. تغییر مسیرها دنبال نمی‌شوند.

تلاش‌های دوباره

ارسال ناموفق بعد از ۱ دقیقه، ۵ دقیقه، ۱۵ دقیقه، ۱ ساعت، ۳ ساعت، ۶ ساعت، ۱۲ ساعت و ۲۴ ساعت دوباره انجام می‌شود. هر تلاش دوباره همان id رویداد را تکرار می‌کند، پس شناسه‌های پردازش‌شده را نگه دارید و تکراری‌ها را نادیده بگیرید. رویدادهای یک فعال‌سازی به ترتیب می‌رسند.

خاموش شدن خودکار

• پاسخ 410 Gone وب‌هوک را فوراً خاموش می‌کند.
• بعد از ۵۰ تلاش ناموفق پیاپی در دست‌کم ۲۴ ساعت، وب‌هوک خاموش می‌شود و اعلان می‌گیرید. endpoint را درست کنید و بعد وب‌هوک را دوباره روشن کنید.
• باطل کردن یک کلید وب‌هوک‌هایش را خاموش می‌کند.

آزمایش و ارسال دوباره

از صفحه وب‌هوک یک رویداد webhook.test بفرستید تا فوراً کد وضعیت، زمان پاسخ و هر خطایی را ببینید. فهرست ارسال‌ها هر ارسال را ۳۰ روز نگه می‌دارد و می‌توانید هرکدام را دوباره بفرستید.