Alege o limbă

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ă
  1. Evenimente
  2. Creează un webhook
  3. Cum arată o livrare
  4. Verifică semnătura
  5. Răspunde repede
  6. Reîncercări
  7. Oprirea automată
  8. Test și relivrare

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

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

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.

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

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 Gone opreș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?

Mai ai nevoie de ajutor?

Scrie-ne. Răspundem la fiecare mesaj, de obicei în câteva ore.

Sau scrie-ne la support@smsgrab.com