Developer-Portal

Schnellstart

1. Lege unter Account → Webhooks einen Endpoint an (öffentliche HTTPS-URL).
2. Wähle die Events aus, die du empfangen willst.
3. Kopiere das einmalig angezeigte Signing-Secret und speichere es sicher.
4. Prüfe in deinem Handler die Signatur (siehe unten) und verarbeite den Payload.

Wie Events zugestellt werden

Jedes Event ist ein HTTP POST mit JSON-Body an deine URL. Wir folgen keinen Redirects und erwarten eine Antwort mit Status 2xx innerhalb von 5 Sekunden. Schlägt die Zustellung fehl, versuchen wir sie kurz erneut (bis zu 3 Versuche). Folgende Header werden gesetzt:

• X-SVL-Event — Event-Name (z.B. recording.created)
• X-SVL-Delivery — eindeutige ID dieser Zustellung
• X-SVL-Signature — HMAC-Signatur in der Form sha256=<hex>

Payloads enthalten bewusst nur IDs, Titel, Zeitstempel und öffentliche Links — niemals E-Mail-Adressen, Passwörter oder Transkript-Inhalte.

Verfügbare Events

{
  "event": "recording.created",
  "createdAt": "2026-06-06T10:00:00.000Z",
  "data": {
    "id": "rec_abc123",
    "title": "Onboarding-Nachricht",
    "shareUrl": "https://sendvoicelink.com/share/xxxx",
    "createdAt": "2026-06-06T10:00:00.000Z"
  }
}

{
  "event": "voiceform.response",
  "createdAt": "2026-06-06T10:00:00.000Z",
  "data": {
    "formId": "vf_abc123",
    "responseId": "vfr_def456",
    "createdAt": "2026-06-06T10:00:00.000Z"
  }
}

{
  "event": "reply.received",
  "createdAt": "2026-06-06T10:00:00.000Z",
  "data": {
    "recordingId": "rec_abc123",
    "replyId": "rep_ghi789",
    "shareUrl": "https://sendvoicelink.com/share/xxxx",
    "createdAt": "2026-06-06T10:00:00.000Z"
  }
}

Signatur prüfen

Verifiziere jede eingehende Zustellung, bevor du sie verarbeitest. Berechne den HMAC-SHA256 über den rohen Request-Body mit deinem Signing-Secret und vergleiche ihn zeitkonstant mit dem Wert aus X-SVL-Signature:

import crypto from "node:crypto";

// In deinem Webhook-Handler: rohen Request-Body als String lesen
// (NICHT erst JSON.parsen und neu serialisieren).
function verify(rawBody, signatureHeader, secret) {
  // Header-Form: "sha256=<hex>"
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");
  const received = (signatureHeader || "").replace(/^sha256=/, "");
  // Zeitkonstanter Vergleich gegen Timing-Angriffe.
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(received, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Eingehende Webhooks

Jede Webhook-Subscription hat einen eingehenden Endpoint. Ein signierter POST an diesen Endpoint erstellt automatisch einen neuen Voice-Link und gibt die Share-URL zurück. Damit kannst du Voice-Links aus deinen eigenen Systemen heraus anlegen.

Endpoint-Format: POST https://sendvoicelink.com/api/webhooks/inbound/{subscriptionId}

Pflicht-Header

• X-SVL-Timestamp: aktueller Unix-Zeitstempel in Sekunden (Toleranz ±5 Minuten)
• X-SVL-Signature: HMAC-SHA256 über timestamp.rawBody, Format sha256=<hex>

JSON-Body

{
  "title": "Rückfrage von Kunde Müller",
  "description": "Bitte kurz beschreiben, was Sie benötigen.",
  "templateId": "customer-feedback"  // optional
}

Beispiel mit curl

#!/bin/sh
SECRET="whsec_dein_signing_secret"
SUB_ID="deine_subscription_id"
TS=$(date +%s)
BODY='{"title":"Rückfrage von Kunde Müller"}'
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -s -X POST \
  "https://sendvoicelink.com/api/webhooks/inbound/$SUB_ID" \
  -H "Content-Type: application/json" \
  -H "X-SVL-Timestamp: $TS" \
  -H "X-SVL-Signature: sha256=$SIG" \
  -d "$BODY"

Bei Erfolg antwortet der Endpoint mit HTTP 201 und {"ok":true,"data":{"id":"…","title":"…","shareUrl":"…"}}. Die zurückgegebene shareUrl kannst du direkt an deine Kunden schicken.

Zapier & Make verbinden

Du brauchst keinen eigenen Code, um SendVoiceLink mit deinen Tools zu verbinden. Zapier und Make bringen fertige Webhook- und HTTP-Bausteine mit. Damit baust du beide Richtungen per Klick auf den oben beschriebenen Events und dem eingehenden Endpoint auf, ganz ohne Server.

Auslöser: ein Ereignis startet deinen Ablauf

Jede neue Aufnahme, jede Voice-Form-Antwort und jede Sprachantwort kann einen Zapier-Zap oder ein Make-Szenario auslösen.

• Zapier: Lege als Trigger Webhooks by Zapier → Catch Hook an und kopiere die angezeigte Catch-Hook-URL.
• Make: Starte das Szenario mit dem Modul Custom Webhook und kopiere die erzeugte Webhook-Adresse.
• Trage diese URL unter Account → Webhooks als Endpoint ein und wähle die gewünschten Events. Fertig.

Aktion: dein Ablauf erstellt einen Voice-Link

Schicke aus einem Zap oder Szenario einen signierten POST an den eingehenden Endpoint, um automatisch einen Voice-Link anzulegen, etwa wenn in deinem CRM ein neuer Kontakt entsteht.

• Make: Bilde die Signatur mit dem eingebauten Modul Crypto → Create HMAC (SHA256). Als Eingabe verkettest du den Zeitstempel, einen Punkt und den unveränderten JSON-Body zu einem String (also timestamp.body) und sendest den POST dann mit dem HTTP-Modul, alles ohne Code.
• Zapier: Berechne die Signatur in einem Code by Zapier-Schritt (eine Zeile HMAC-SHA256, siehe Abschnitt „Signatur prüfen") und sende anschliessend mit Webhooks by Zapier → Custom Request.

Subscription-ID und Signing-Secret findest du jeweils unter Account → Webhooks. Der Endpoint und die Header sind im Abschnitt „Eingehende Webhooks" oben beschrieben.