Webhooks

Webhooks sturen gebeurtenissen naar je server op het moment dat ze gebeuren, zodat je niet hoeft te pollen. Een webhook hoort bij één API-sleutel. Hij ontvangt de gebeurtenissen van nummers die met die sleutel zijn gekocht, plus waarschuwingen over een laag saldo van je account.

Gebeurtenissen

Een webhook maken

Open in Account > Ontwikkelaars een sleutel en voeg een webhook toe met de URL, de gewenste gebeurtenissen en een optionele beschrijving. Elke sleutel kan maximaal 3 webhooks hebben.

De URL moet:

• beginnen met https://;
• een hostnaam gebruiken, geen IP-adres;
• naar een openbaar adres leiden. Privénetwerken, localhost en vergelijkbare bereiken worden geweigerd.

Je krijgt een ondertekeningsgeheim dat begint met whsec_. Net als een API-sleutel wordt het maar één keer getoond. Je kunt het later vernieuwen, en ook dat vraagt om je wachtwoord.

Hoe een levering eruitziet

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

De handtekening controleren

SmsGrab-Signature bevat een tijdstempel t en v1, de HMAC-SHA256 van t, een punt en de ruwe body van het verzoek, met je geheim als sleutel. Weiger leveringen waarvan de tijdstempel meer dan 300 seconden van je klok afwijkt, en vergelijk de handtekeningen in constante tijd.

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

Controleer altijd de ruwe body precies zoals je hem ontving, voordat je de JSON verwerkt.

Snel antwoorden

Antwoord binnen 10 seconden met een willekeurige 2xx-status en doe traag werk achteraf, bijvoorbeeld in een wachtrij. Omleidingen worden niet gevolgd.

Nieuwe pogingen

Een mislukte levering wordt opnieuw geprobeerd na 1 minuut, 5 minuten, 15 minuten, 1 uur, 3 uur, 6 uur, 12 uur en 24 uur. Een nieuwe poging herhaalt dezelfde id van de gebeurtenis, dus onthoud de id's die je hebt verwerkt en sla dubbele over. Gebeurtenissen voor één activering komen op volgorde binnen.

Automatisch uitzetten

• Antwoorden met 410 Gone zet de webhook meteen uit.
• Na 50 mislukte pogingen op rij over minstens 24 uur wordt de webhook uitgezet en krijg je een melding. Herstel je endpoint en zet de webhook daarna weer aan.
• Een sleutel intrekken zet zijn webhooks uit.

Testen en opnieuw leveren

Stuur een gebeurtenis webhook.test vanaf de pagina van de webhook om meteen de statuscode, de reactietijd en eventuele fouten te zien. De lijst met leveringen bewaart elke levering 30 dagen, en je kunt ze allemaal opnieuw sturen.