Notificaciones por webhook

Consultar en bucle gasta peticiones y añade retraso. Un webhook llega a tu servidor en el mismo segundo en que aparece el código.

• Sin bucle de consulta: tu cuota diaria de peticiones se dedica al trabajo real y no a comprobar estados.
• Menos latencia: el código llega a tu sistema en cuanto lo recibimos, no en tu siguiente consulta.
• También los eventos finales: las cancelaciones y las expiraciones llegan con el estado del reembolso, así tu contabilidad se mantiene al día.

Tres eventos, todos sobre una misma activación.

Cada petición lleva una firma HMAC SHA256 construida con la marca de tiempo y el cuerpo en bruto.

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)

La marca de tiempo forma parte de la cadena firmada, así que puedes rechazar lo que tenga más de unos minutos. Compara las firmas en tiempo constante.

Usa X-SMSBulk-Event-Id como clave de idempotencia. Los reintentos del mismo evento llevan el mismo id.