Виберіть мову

Вебхуки

Отримуйте події активацій на свій сервер у реальному часі, перевіряйте заголовок SmsGrab-Signature і розберіться з повторами, тестовими доставками й автоматичним вимкненням.

На цій сторінці
  1. Події
  2. Створення вебхука
  3. Як виглядає доставка
  4. Перевірка підпису
  5. Відповідайте швидко
  6. Повтори
  7. Автоматичне вимкнення
  8. Тест і повторна доставка

Вебхуки надсилають події на ваш сервер у момент, коли вони відбуваються, тож опитувати API не потрібно. Вебхук належить одному API-ключу. Він отримує події номерів, куплених цим ключем, а також сповіщення про низький баланс облікового запису.

Події

Подія Коли
activation.created Куплено номер
activation.code_received Кожне нове SMS, з усіма повідомленнями на цей момент
activation.completed Завершено вами або після закінчення часу після коду
activation.cancelled Скасовано до коду, кошти повернуто
activation.expired Код не надійшов вчасно, кошти повернуто
activation.refunded Будь-яке повернення списання
balance.low Баланс опустився нижче заданого вами порогу
webhook.test Тестова доставка, яку запустили ви

Створення вебхука

В Обліковий запис > Розробникам відкрийте ключ і додайте вебхук із URL-адресою, потрібними подіями й необов'язковим описом. Кожен ключ може мати до 3 вебхуків.

URL-адреса має:

  • починатися з https://;
  • використовувати ім'я хоста, а не IP-адресу;
  • вести на публічну адресу. Приватні мережі, localhost і подібні діапазони відхиляються.

Ви отримаєте секрет для підпису, що починається з whsec_. Як і API-ключ, його показують лише один раз. Згодом його можна змінити, і це теж вимагатиме пароль.

Як виглядає доставка

HTTP
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, крапки й необробленого тіла запиту з вашим секретом як ключем. Відхиляйте доставки, у яких позначка часу розходиться з вашим годинником більш ніж на 300 секунд, і порівнюйте підписи за сталий час.

PHP
[$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);
Python
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", ""))
JavaScript
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 протягом 10 секунд, а тривалу обробку виконуйте потім, наприклад у черзі. Переспрямування не виконуються.

Повтори

Невдала доставка повторюється через 1 хвилину, 5 хвилин, 15 хвилин, 1 годину, 3 години, 6 годин, 12 годин і 24 години. Повтор містить той самий id події, тож запам'ятовуйте оброблені ідентифікатори й пропускайте дублікати. Події однієї активації надходять по черзі.

Автоматичне вимкнення

  • Відповідь 410 Gone одразу вимикає вебхук.
  • Після 50 невдалих спроб поспіль упродовж щонайменше 24 годин вебхук вимикається, і ви отримуєте сповіщення. Виправте ендпоінт, а потім знову ввімкніть вебхук.
  • Відкликання ключа вимикає його вебхуки.

Тест і повторна доставка

Надішліть подію webhook.test зі сторінки вебхука, щоб одразу побачити код статусу, час відповіді й можливу помилку. Список доставок зберігає кожну доставку 30 днів, і будь-яку з них можна надіслати повторно.

Ця стаття була корисною?

Досі потрібна допомога?

Напишіть нам. Ми відповідаємо на кожне повідомлення, зазвичай протягом кількох годин.

Або напишіть на support@smsgrab.com