Scegli una lingua

Webhook

Ricevi in tempo reale sul tuo server gli eventi di attivazione, verifica l'intestazione SmsGrab-Signature e scopri nuovi tentativi, consegne di prova e disattivazione automatica.

In questa pagina
  1. Eventi
  2. Creare un webhook
  3. Com'è fatta una consegna
  4. Verificare la firma
  5. Rispondi in fretta
  6. Nuovi tentativi
  7. Disattivazione automatica
  8. Provare e reinviare

I webhook inviano gli eventi al tuo server nel momento in cui accadono, così non devi interrogare continuamente l'API. Un webhook appartiene a una chiave API. Riceve gli eventi dei numeri acquistati con quella chiave e gli avvisi di saldo basso del tuo account.

Eventi

Evento Quando
activation.created È stato acquistato un numero
activation.code_received A ogni nuovo SMS, con tutti i messaggi ricevuti
activation.completed Concluso da te, oppure tempo scaduto dopo un codice
activation.cancelled Annullato prima di un codice, rimborsato
activation.expired Nessun codice in tempo, rimborsato
activation.refunded Qualsiasi rimborso dell'addebito
balance.low Il saldo è sceso sotto la soglia che hai impostato
webhook.test Una consegna di prova avviata da te

Creare un webhook

In Account > Sviluppatori apri una chiave e aggiungi un webhook con URL, eventi desiderati e una descrizione facoltativa. Ogni chiave può avere fino a 3 webhook.

L'URL deve:

  • iniziare con https://;
  • usare un nome host, non un indirizzo IP;
  • puntare a un indirizzo pubblico. Reti private, localhost e intervalli simili vengono rifiutati.

Ricevi un segreto di firma che inizia con whsec_. Come una chiave API, viene mostrato una sola volta. Puoi rinnovarlo in seguito, e anche questo richiede la password.

Com'è fatta una consegna

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" } } }

Verificare la firma

SmsGrab-Signature contiene un timestamp t e v1, l'HMAC-SHA256 di t, un punto e il corpo grezzo della richiesta, calcolato con il tuo segreto. Rifiuta le consegne il cui timestamp si discosta di oltre 300 secondi dal tuo orologio e confronta le firme in tempo costante.

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);
}

Verifica sempre il corpo esattamente come l'hai ricevuto, prima di interpretare il JSON.

Rispondi in fretta

Rispondi con qualsiasi stato 2xx entro 10 secondi e svolgi dopo il lavoro lento, per esempio in una coda. I reindirizzamenti non vengono seguiti.

Nuovi tentativi

Una consegna non riuscita viene ritentata dopo 1 minuto, 5 minuti, 15 minuti, 1 ora, 3 ore, 6 ore, 12 ore e 24 ore. Un nuovo tentativo ripete lo stesso id dell'evento: tieni traccia degli identificativi già elaborati e scarta i duplicati. Gli eventi di una stessa attivazione arrivano in ordine.

Disattivazione automatica

  • Rispondere 410 Gone disattiva subito il webhook.
  • Dopo 50 tentativi falliti di seguito nell'arco di almeno 24 ore, il webhook viene disattivato e ricevi una notifica. Correggi il tuo endpoint, poi riattiva il webhook.
  • La revoca di una chiave disattiva i suoi webhook.

Provare e reinviare

Invia un evento webhook.test dalla pagina del webhook per vedere subito codice di stato, tempo di risposta ed eventuale errore. L'elenco delle consegne conserva ogni consegna per 30 giorni e puoi reinviarne una qualsiasi.

Questo articolo ti è stato utile?

Hai ancora bisogno di aiuto?

Scrivici. Rispondiamo a ogni messaggio, di solito entro poche ore.

Oppure scrivici a support@smsgrab.com