SMS- und Anruf-Codes per Webhook empfangen: API-Leitfaden

Ein Webhook schickt jede SMS und jeden Anruf auf deiner Nummer an deinen Server. Ein kurzer Anruf kommt mit seinem Text und dem vorgelesenen Code an.

Ein Webhook schickt jede SMS und jeden Anruf auf deiner Nummer an deinen Server, sobald sie eintreffen. Seit November 2026 kommt ein kurzer Anruf zusammen mit seinem Text und dem darin vorgelesenen Code an, sodass dein Code auch einen Sprachcode als Text erhält.

In diesem Leitfaden richtest du den Empfänger ein, prüfst, dass jede Anfrage wirklich von uns kommt, und verarbeitest beide Arten von Codes. Er setzt voraus, dass du schon einen API-Schlüssel und eine Nummer hast. Falls nicht, beginne mit SMS-Verifizierung per API automatisieren.

Warum manche Codes als Anruf kommen

Viele Dienste bieten „Stattdessen anrufen“ an, wenn keine SMS ankommt, und einige schicken nur Sprachcodes. Ein Roboter liest die Ziffern vor. Mit einer privaten Nummer von SMS Activate App kommt dieser Anruf auf deiner Nummer an, genau wie eine SMS.

Jeder aufgezeichnete Anruf von bis zu einer Minute wird beim Eingang in Text umgewandelt. Du bekommst:

  • transcript: was im Anruf gesagt wurde, oder null.
  • code: der darin vorgelesene Bestätigungscode (4 bis 8 Ziffern), oder null.
  • transcriptStatus: done, empty (keine Sprache), failed, toolong (länger als eine Minute), overbudget oder off.

Der Link zur Aufzeichnung funktioniert 24 Stunden. Der Text bleibt erhalten.

Schritt 1: Die Nummer auf deinen Server richten

Lege den Webhook für eine Nummer fest:

Die Adresse muss HTTPS verwenden und unsere Prüfung mit einem 2xx-Status beantworten, bevor sie gespeichert wird. Willst du Ereignisse für alle deine Nummern auf einmal erhalten, setze stattdessen webhookUrl im Konto mit PATCH /v1/me.

Schritt 2: Das Signatur-Secret holen

Die Antwort lautet {"secret": "whsec_..."} und wird nur einmal angezeigt. Speichere das Secret neben deinem API-Schlüssel. Jeder Aufruf erstellt ein neues Secret, und das alte gilt ab der nächsten Zustellung nicht mehr. Wechsle es deshalb nur, wenn du deinen Server gleichzeitig aktualisieren kannst.

Schritt 3: Jede Anfrage prüfen

Jede Anfrage enthält drei Header:

  • x-vpn-event: sms.received, call.received, recording.ready und weitere.
  • x-vpn-timestamp: der Zeitpunkt der Signatur, in Unix-Sekunden.
  • x-vpn-signature: v1= und ein HMAC-SHA256 als Hex-Wert.

Die Signatur ist ein HMAC-SHA256 mit deinem Secret über v1.<timestamp>.<raw body>. Berechne sie über die rohen Bytes, vor jedem JSON-Parsing, und lehne einen Zeitstempel ab, der mehr als fünf Minuten von deiner Uhr abweicht.

In Node.js mit Express:

Antworte schnell mit einem 2xx und erledige aufwendige Arbeit erst danach.

Schritt 4: Den Code aus beiden Ereignisarten übernehmen

Eine SMS (sms.received):

Die Aufzeichnung eines Anrufs (recording.ready, wenige Sekunden nach dem Ende des Anrufs):

Ein Handler deckt beides ab:

Nutze lieber das Feld code, statt das Transkript selbst auszuwerten: Der Roboter wiederholt die Ziffern oft oder liest sie einzeln vor, und code enthält sie bereits als einen einzigen String.

Schritt 5: Vor echtem Traffic testen

  • POST /v1/me/webhook-test sendet ein webhook.test-Ereignis an deinen Empfänger.
  • GET /v1/me/webhook-deliveries listet die letzten Zustellungen auf: das Ereignis, ob es zugestellt wurde, den Statuscode deines Servers und die Anzahl der Versuche.

Schlägt eine Zustellung fehl, schau zuerst dort nach. Übliche Ursachen sind ein falsches Secret, ein Body, der vor der Prüfung geparst wurde, oder eine langsame Antwort.

Kein Webhook? Anrufe per API lesen

Ohne Server liest du die Anrufe einer Nummer dann, wenn du sie brauchst:

Jeder Anruf enthält dieselben Felder transcript, code und transcriptStatus. In deinem Konto auf der Website steht der Code unter dem Anruf und lässt sich mit einem Tippen kopieren.

Was Anrufe und SMS kosten

Eingehende Anrufe (pro Minute) und SMS auf einer Nummer werden zu einem Preis je Land von deinem Guthaben abgebucht. Der Preis wird als usagePricing (callCents, smsCents, advanceUsd) bei Ländern, Suchergebnissen und deinen Nummern zurückgegeben. Bei leerem Guthaben funktioniert eine Nummer bis zu einem kleinen Vorschuss weiter. Danach werden eingehende Anrufe abgelehnt, bis du Guthaben auflädst, SMS kommen aber weiterhin an. Details findest du unter Preise.

Nächste Schritte