Уведомления через вебхуки

Опрос тратит запросы и добавляет задержку. Вебхук доходит до вашего сервера в ту же секунду, когда приходит код.

• Никакого цикла опроса: дневная квота запросов уходит на реальную работу, а не на проверку статуса.
• Меньше задержка: код попадает в вашу систему сразу, а не при следующем опросе.
• Терминальные события тоже приходят: отмена и истечение срока приходят со статусом возврата, ваш учёт остаётся в синхроне.

Три события, все об одной активации.

Каждый запрос несёт подпись HMAC SHA256, построенную из метки времени и сырого тела.

X-SMSBulk-Signature: t=<unix_seconds>,v1=<hex_hmac_sha256>
signed_string = "<t>.<raw_request_body>"

Node.js

const crypto = require('crypto');

function verify(rawBody, header, secret) {
  const pairs = header.split(',').map((p) => {
    const i = p.indexOf('=');
    return [p.slice(0, i), p.slice(i + 1)];
  });

  const t = pairs.find(([k]) => k === 't')?.[1];
  // During a rotate window more than one signature arrives: collect them all.
  const signatures = pairs.filter(([k]) => k === 'v1').map(([, v]) => v);
  if (!t || signatures.length === 0) return false;

  // Replay window: reject anything older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  return signatures.some(
    (s) =>
      s.length === expected.length &&
      crypto.timingSafeEqual(
        Buffer.from(s, 'hex'),
        Buffer.from(expected, 'hex'),
      ),
  );
}

Python

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    pairs = [p.split("=", 1) for p in header.split(",")]

    t = next((v for k, v in pairs if k == "t"), None)
    # During a rotate window more than one signature arrives: collect them all.
    signatures = [v for k, v in pairs if k == "v1"]
    if t is None or not signatures:
        return False

    # Replay window: reject anything older than 5 minutes.
    if abs(time.time() - int(t)) > 300:
        return False

    expected = hmac.new(
        secret.encode(),
        f"{t}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()

    return any(hmac.compare_digest(s, expected) for s in signatures)

Метка времени входит в подписываемую строку, поэтому можно отклонять уведомления старше нескольких минут. Сравнивайте подписи за постоянное время.

Используйте X-SMSBulk-Event-Id как ключ идемпотентности. Повторы того же события приходят с тем же id.