Webhooks

Webhooks senden Ereignisse in dem Moment an deinen Server, in dem sie passieren, damit du nicht ständig abfragen musst. Ein Webhook gehört zu einem API-Schlüssel. Er empfängt die Ereignisse der mit diesem Schlüssel gekauften Nummern sowie Warnungen bei niedrigem Guthaben für dein Konto.

Ereignisse

Einen Webhook anlegen

Öffne unter Konto > Entwickler einen Schlüssel und füge einen Webhook mit URL, den gewünschten Ereignissen und einer optionalen Beschreibung hinzu. Jeder Schlüssel kann bis zu 3 Webhooks haben.

Die URL muss:

• mit https:// beginnen;
• einen Hostnamen verwenden, keine IP-Adresse;
• zu einer öffentlichen Adresse führen. Private Netze, localhost und ähnliche Bereiche werden abgelehnt.

Du erhältst ein Signaturgeheimnis, das mit whsec_ beginnt. Wie ein API-Schlüssel wird es nur einmal angezeigt. Du kannst es später erneuern, was ebenfalls nach deinem Passwort fragt.

So sieht eine Zustellung aus

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

Die Signatur prüfen

SmsGrab-Signature enthält einen Zeitstempel t und v1, den HMAC-SHA256 aus t, einem Punkt und dem unveränderten Request-Body, berechnet mit deinem Geheimnis. Lehne Zustellungen ab, deren Zeitstempel mehr als 300 Sekunden von deiner Uhr abweicht, und vergleiche die Signaturen in konstanter Zeit.

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

Prüfe immer den Body genau so, wie du ihn empfangen hast, bevor du das JSON auswertest.

Schnell antworten

Antworte innerhalb von 10 Sekunden mit einem beliebigen 2xx-Status und erledige langsame Arbeit danach, etwa in einer Warteschlange. Weiterleitungen werden nicht verfolgt.

Wiederholungen

Eine fehlgeschlagene Zustellung wird nach 1 Minute, 5 Minuten, 15 Minuten, 1 Stunde, 3 Stunden, 6 Stunden, 12 Stunden und 24 Stunden wiederholt. Eine Wiederholung trägt dieselbe Ereignis-id, merke dir also verarbeitete IDs und überspringe Duplikate. Ereignisse einer Aktivierung kommen in der richtigen Reihenfolge an.

Automatisches Abschalten

• Eine Antwort 410 Gone schaltet den Webhook sofort ab.
• Nach 50 fehlgeschlagenen Versuchen in Folge über mindestens 24 Stunden wird der Webhook abgeschaltet und du bekommst eine Benachrichtigung. Repariere deinen Endpunkt und schalte den Webhook dann wieder ein.
• Wird ein Schlüssel widerrufen, werden seine Webhooks abgeschaltet.

Testen und erneut zustellen

Sende über die Seite des Webhooks ein webhook.test-Ereignis, um Statuscode, Antwortzeit und etwaige Fehler sofort zu sehen. Die Zustellliste bewahrt jede Zustellung 30 Tage auf, und du kannst jede davon erneut senden.