Schnittstelle & Webhooks

Nachrichten aus der eigenen Software heraus versenden — und erfahren, wann sie abgerufen wurden.

Das Wichtigste zuerst, weil es der einzige echte Unterschied zur Bedienoberfläche ist. Im Browser wird Ihr Inhalt auf Ihrem Gerät verschlüsselt; unser Server sieht ihn nie. Über die Schnittstelle gilt das nur, wenn Sie selbst verschlüsseln und ciphertext schicken. Schicken Sie stattdessen message im Klartext, verschlüsseln wir für Sie — dann liegt der Inhalt für den Bruchteil einer Sekunde unverschlüsselt in unserem Arbeitsspeicher. Gespeichert oder protokolliert wird er dort nicht, aber die Aussage „technisch ausgeschlossen" gilt für diesen Weg nicht. Beide Wege sind zulässig — Sie sollen nur wissen, welchen Sie nehmen.

Schlüssel anlegen

Im Konto unter Schnittstelle & Webhooks. Der Schlüssel wird genau einmal angezeigt; wir speichern nur eine Prüfsumme und können ihn nicht wiederherstellen. Geht er verloren, widerrufen Sie ihn und erzeugen einen neuen. Schnittstelle und Webhooks sind Bestandteil des Business-Tarifs.

Nachricht senden

POST https://schluesselbot.de/v1/send

curl -X POST https://schluesselbot.de/v1/send \
  -H "Authorization: Bearer sb_live_XXXXXXXX_…" \
  -H "Content-Type: application/json" \
  -d '{
        "recipient_email": "empfaenger@firma.de",
        "message": "Zugang: kunde42 / T7!kq2wZ",
        "ttl_hours": 48,
        "sender_name": "Kanzlei Weber",
        "notify_email": "buero@kanzlei-weber.de"
      }'
FeldPflichtBedeutung
recipient_emailjaWer die Nachricht bekommt. Der Link geht an diese Adresse.
messageja*Klartext, den wir verschlüsseln. Bis 256 KB.
ciphertext + fragmentja*Alternative: Sie verschlüsseln selbst (AES-256-GCM, 12-Byte-Nonce vorangestellt, base64). fragment ist der Schlüssel als base64url — er landet nur im Link, nie bei uns.
ttl_hoursnein1 bis 168 Stunden. Voreinstellung 48.
sender_nameneinSteht in der Benachrichtigung, damit der Empfänger weiß, von wem sie kommt.
notify_emailneinBekommt eine Nachricht, sobald abgerufen wurde.

* Entweder message oder ciphertext — eines von beiden muss dabei sein.

Antwort:

{
  "id": "8f3c…",
  "link": "https://schluesselbot.de/r/8f3c…#kQ2…",
  "expires_at": "2026-08-17T09:00:00+00:00",
  "modus": "vom Server verschlüsselt"
}

Fehler

CodeBedeutung
401Schlüssel fehlt, ist falsch oder wurde widerrufen.
403Das Konto hat keinen Business-Tarif.
400Angaben unvollständig — die Meldung sagt, welche.
429Zu viele Sendungen in kurzer Zeit. Kurz warten und erneut.
502Der Tresor ist gerade nicht erreichbar. Erneut versuchen; es wurde nichts gesendet.

Webhooks

Ein Webhook meldet Ihrer Software, dass etwas passiert ist. Eingerichtet wird er im Konto. Zugestellt wird nur an https-Adressen im öffentlichen Netz — Ziele im lokalen Netz lehnen wir ab, sonst wäre der Webhook ein Werkzeug, um von unserem Server aus fremde Netze abzuklopfen.

Wir senden POST mit diesem Rumpf:

{
  "event": "consumed",
  "zeit": "2026-08-15T09:12:33+00:00",
  "daten": { "id": "8f3c…", "mit_anhang": false }
}

Und diesen Köpfen:

X-Schluesselbot-Event: consumed
X-Schluesselbot-Signature: sha256=<HMAC des Rumpfes mit Ihrem Geheimnis>

Prüfen Sie die Signatur immer — sonst kann jeder, der Ihre Adresse kennt, erfundene Ereignisse einspielen:

# PHP
$erwartet = 'sha256=' . hash_hmac('sha256', $rumpf, $geheimnis);
if (!hash_equals($erwartet, $_SERVER['HTTP_X_SCHLUESSELBOT_SIGNATURE'])) { http_response_code(401); exit; }

Antworten Sie mit einem Statuscode aus dem 2xx-Bereich. Bleibt die Antwort aus, versuchen wir es beim nächsten Ereignis erneut; nach 20 Fehlversuchen in Folge stellen wir für diesen Webhook nichts mehr zu und zeigen Ihnen den Zustand im Konto. Wir warten höchstens 5 Sekunden auf Ihre Antwort — ein langsamer Server darf nie das Öffnen einer Nachricht verzögern.

Was die Schnittstelle bewusst nicht kann

Grenzen