Webhook-uri
Primește evenimentele activărilor pe server în timp real, verifică antetul SmsGrab-Signature și înțelege reîncercările, livrările de test și oprirea automată.
Pe această pagină
Webhook-urile trimit evenimente către serverul tău în momentul în care se întâmplă, așa că nu mai trebuie să interoghezi. Un webhook aparține unei singure chei API. Primește evenimentele numerelor cumpărate cu acea cheie, plus alertele de sold scăzut ale contului.
Evenimente
| Eveniment | Când |
|---|---|
activation.created |
S-a cumpărat un număr |
activation.code_received |
Fiecare SMS nou, cu toate mesajele de până atunci |
activation.completed |
Finalizat de tine sau când a expirat timpul după un cod |
activation.cancelled |
Anulat înainte de un cod, rambursat |
activation.expired |
Niciun cod la timp, rambursat |
activation.refunded |
Orice rambursare a plății |
balance.low |
Soldul a scăzut sub pragul setat de tine |
webhook.test |
O livrare de test pornită de tine |
Creează un webhook
În Cont > Dezvoltatori, deschide o cheie și adaugă un webhook cu URL-ul, evenimentele dorite și o descriere opțională. Fiecare cheie poate avea până la 3 webhook-uri.
URL-ul trebuie:
- să înceapă cu
https://; - să folosească un nume de gazdă, nu o adresă IP;
- să ducă la o adresă publică. Rețelele private, localhost și intervalele similare sunt refuzate.
Primești un secret de semnare care începe cu whsec_. La fel ca o cheie API, este afișat o singură dată. Îl poți schimba mai târziu, ceea ce îți cere și parola.
Cum arată o livrare
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" } } }
Verifică semnătura
SmsGrab-Signature conține o marcă de timp t și v1, adică HMAC-SHA256 al lui t, un punct și corpul brut al cererii, cu secretul tău drept cheie. Respinge livrările a căror marcă de timp diferă cu mai mult de 300 de secunde de ceasul tău și compară semnăturile în timp constant.
[$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);
}
Verifică mereu corpul brut exact cum l-ai primit, înainte să parsezi JSON-ul.
Răspunde repede
Răspunde cu orice stare 2xx în 10 secunde și fă munca lentă după aceea, de exemplu într-o coadă. Redirecționările nu sunt urmate.
Reîncercări
O livrare eșuată este reîncercată după 1 minut, 5 minute, 15 minute, 1 oră, 3 ore, 6 ore, 12 ore și 24 de ore. O reîncercare repetă același id al evenimentului, așa că ține minte id-urile procesate și sari peste duplicate. Evenimentele unei activări sosesc în ordine.
Oprirea automată
- Un răspuns
410 Goneoprește webhook-ul imediat. - După 50 de încercări eșuate la rând într-un interval de cel puțin 24 de ore, webhook-ul este oprit și primești o notificare. Repară endpointul, apoi pornește din nou webhook-ul.
- Revocarea unei chei îi oprește webhook-urile.
Test și relivrare
Trimite un eveniment webhook.test din pagina webhook-ului ca să vezi imediat codul de stare, timpul de răspuns și eventualele erori. Lista livrărilor păstrează fiecare livrare 30 de zile și o poți retrimite pe oricare.
Ți-a fost util acest articol?
Mulțumim! Ne bucurăm că te-a ajutat.