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
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
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.
[$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);
}
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 Gonedisattiva 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?
Grazie! Siamo felici che ti sia stato utile.