Ein Webhook-Signing-Secret gehört zu den Zugangsdaten und ist kein Detail der Einrichtung. Senden Sie es so, wie Sie ein Passwort senden würden: Bestätigen Sie, wer es erhält, übergeben Sie es über einen Kanal, der keine Kopien behält, und sorgen Sie dafür, dass es in einem Secrets-Speicher landet und nicht in einem Ticket. Kurz gesagt: ein Einmal-Link an einen geprüften Kontakt, die Anleitung zur Einrichtung getrennt davon.
Der Rest dieses Leitfadens behandelt die Wahl des Kanals, die Prüfungen vor dem Senden, was der Kunde mit dem Wert tun sollte und wie Sie Erneuerung und Fehlersuche handhaben, ohne das Secret je wieder einzufügen.
Welcher Kanal sollte das Secret transportieren?
Wählen Sie den Kanal nach zwei Kriterien: Können Sie bestätigen, wer ihn öffnen kann, und wie viele Kopien bleiben zurück? E-Mail und Chat scheitern am zweiten Kriterium, denn jede Nachricht wird lange nach der Übergabe noch aufbewahrt, synchronisiert und exportiert.
| Methode | Was sie Ihnen bietet | Vor dem Senden prüfen |
|---|---|---|
| Kundenportal mit Anmeldung | Zugriff für namentlich bekannte Personen, den Sie widerrufen können | Das Konto gehört dem richtigen Kontakt |
| Einmal-Link | Nach einmaligem Öffnen gelöscht, nichts bleibt in der Nachricht zurück | Die Adresse, an die Sie ihn senden, separat geprüft |
| Verschlüsselter Messenger | Geschützt während der Übertragung | Wer sonst noch diese Unterhaltung öffnen kann |
Ein Kundenportal mit persönlichen Zugängen ist die erste Wahl, wenn es eines gibt. Geben Sie einer namentlich bekannten Person Zugriff, nicht einem gemeinsamen Projekt-Thread, und entziehen Sie den Zugriff, sobald die Übergabe abgeschlossen ist.
Ein Einmal-Link hält das Secret aus der E-Mail oder Chatnachricht heraus, mit der Sie sich abstimmen. Bei LinkPilot wird das Secret in Ihrem Browser verschlüsselt, bevor es gespeichert wird, die gespeicherte Kopie wird nach einmaligem Öffnen gelöscht, und Sie können den Link nach einer Stunde, einem Tag oder einer Woche ablaufen lassen. In den Pro-Tarifen kommt eine Passphrase hinzu, die Sie über einen separaten Kanal weitergeben. Diese Kontrollen begrenzen die Übergabe. Sie ersetzen nicht die Prüfung, ob am anderen Ende die richtige Person sitzt.
Ein verschlüsselter Messenger ist die Notlösung, wenn keiner der beiden Wege oben praktikabel ist. Verschlüsselung während der Übertragung hilft nicht gegen eine falsch adressierte Nachricht oder eine zu große Gruppe, die Prüfung des Empfängers zählt hier also noch mehr.
Was Sie auch wählen: Nutzen Sie E-Mail und Chat im Klartext nur zur Abstimmung. Auch Dienste, die während der Übertragung verschlüsseln, entziehen Ihnen die Kontrolle über Aufbewahrung, Backups und Kontozugriff.
Kunden und Empfänger prüfen
Ein sicherer Kanal nützt nichts, wenn das Secret im falschen Postfach landet. Bestätigen Sie vor dem Senden, dass die anfragende Person für die Integration zuständig ist und dass der geplante Weg wirklich zu ihr führt.
- Identität über einen bekannten Eintrag bestätigen. Nutzen Sie einen vertrauenswürdigen Kontakteintrag, eine bestehende Geschäftsbeziehung oder den etablierten Prozess des Kunden. Eine neue anfragende Person, ein plötzlicher Wechsel des Ansprechpartners oder ungewöhnliche Eile verdienen eine unabhängige Prüfung.
- Lesen Sie die Adresse Zeichen für Zeichen, besonders wenn Sie sie aus einem Ticket oder einer aktuellen Nachricht kopieren. Ähnliche Namen und geteilte Postfächer sind die typischen Fehlerquellen.
- Prüfen Sie, wer sonst Zugriff hat. Sehen Sie sich vor dem Teilen über ein Portal oder einen Workspace die Mitgliederliste an und entfernen Sie alle, die das Secret nicht brauchen.
- Bestätigen Sie den Empfang über einen zweiten Kanal. Ging der Link per E-Mail, fragen Sie über eine bekannte Telefonnummer oder den üblichen Projektkanal nach, ob der Zugriff geklappt hat. Das Secret gehört nicht in diese Nachricht.
Teilen Sie das Secret mit der einen Person, die den Endpunkt konfiguriert, und lassen Sie sie es im eigenen Secrets-Speicher des Kunden ablegen. Brauchen es mehrere Personen im Entwicklungsteam, regeln die Zugriffsrechte dieses Speichers, wer es sieht, nicht separate Kopien für jede einzelne Person.
Das Secret vor der Übergabe vorbereiten
Legen Sie fest, zu welcher Integration das Secret gehört, wo der Kunde es aufbewahren soll und wie lange die Übergabe offen bleibt. Diese Vorbereitung macht spätere Erneuerung und Fehlersuche deutlich übersichtlicher.
- Ein Secret pro Kunde oder Endpunkt. Wiederverwendung bedeutet, dass ein einzelnes Leck jede Integration mit demselben Wert erreicht und die Erneuerung bei einem Kunden alle anderen stört. Führen Sie intern Buch, zu welchem Endpunkt welches Secret gehört, ohne den Wert in Projektnotizen zu kopieren.
- Bewahren Sie Ihre eigene Kopie in einem Secrets-Manager auf. Nicht in einer lokalen Textdatei, einem Ticket oder einem geteilten Dokument. Dieselbe Disziplin gilt beim Teilen von API-Schlüsseln: Begrenzen Sie, wer an das Secret kommt, und halten Sie die Übergabe kurz.
- Legen Sie ein Zeitfenster zum Abrufen fest. Geben Sie dem Kunden genug Zeit, den Wert abzuholen und die Einrichtung abzuschließen, und nicht mehr. Ein Link, der nach einmaligem Öffnen gelöscht wird und nach einem Tag abläuft, deckt die meisten Übergaben ab. Ist das Zeitfenster verstrichen, erstellen Sie einen neuen, statt den alten wieder zu öffnen.
- Senden Sie die Anleitung zur Einrichtung separat. Die URL des Endpunkts, der Signatur-Header und die Prüfschritte gehören in die Dokumentation des Kunden oder in den Projektkanal. Sind sie vom Secret getrennt, ist eine kopierte Anleitungsseite nicht gleichzeitig ein kopiertes Secret.
Dem Kunden beim sicheren Speichern und Nutzen helfen
Die Übergabe ist nicht abgeschlossen, wenn der Kunde den Wert lesen kann. Sie ist abgeschlossen, wenn der Server ihn sicher lesen kann und damit eingehende Signaturen prüft.
- Speichern Sie es in einem Secrets-Manager oder einer geschützten Umgebungsvariable, die der Serverprozess lesen kann. Zugriff haben nur die Anwendung und die Personen, die sie betreiben.
- Halten Sie es aus Quellcode, Logs und Webhook-Payloads heraus. Das Secret dient dazu, eine Signatur zu berechnen oder zu prüfen. Es wird nie im Request-Body übertragen und sollte weder in Debug-Ausgaben noch in Repositorys oder Support-Tickets auftauchen. Prüfen Sie, was Ihre Deployment-Tools mitschneiden, bevor Sie ausführliche Diagnosen einschalten.
- Prüfen Sie Signaturen auf dem Server. Der Empfänger berechnet die Signatur mit dem gemeinsamen Secret über den unveränderten Request-Body neu und vergleicht sie mit dem Header, den der Absender gesetzt hat. Die Signatur beweist, dass die Anfrage echt und unverändert ist. Sie verschlüsselt die Payload nicht. Der Leitfaden von HackerOne zum Signieren von Webhooks erklärt, warum der unveränderte Body und das richtige Secret beide entscheidend sind.
- Lösen Sie ein Testereignis aus. Lassen Sie den Kunden bestätigen, dass eine gültige Signatur akzeptiert und eine absichtlich fehlerhafte abgelehnt wird. So fallen die üblichen Fehler auf: das Secret des falschen Endpunkts oder ein Body, der vor der Prüfung geparst wurde. Trennen Sie Test- und Produktionszugangsdaten, wo die Integration das unterstützt.
Das Risiko nach der Übergabe senken
Die Übergabe sollte einen brauchbaren Nachweis hinterlassen, keine Spur zusätzlicher Kopien.
- Halten Sie fest, wer berechtigt wurde und wann. Protokollieren Sie den Empfänger, den Endpunkt oder Kunden und den Zeitpunkt der Übergabe. Niemals den Wert. Können Sie nicht sagen, ob ein Link geöffnet wurde oder wer auf einen geteilten Ordner zugreifen konnte, ist das ein Grund, den Prozess beim nächsten Mal enger zu fassen.
- Erneuern Sie bei jedem Verdacht auf ein Leck. Ein Secret, das in ein Ticket eingefügt, an die falsche Adresse geschickt oder in einem Log gefunden wurde, ist nicht mehr privat. Erzeugen Sie einen Ersatz, aktualisieren Sie den Endpunkt und machen Sie den alten Wert ungültig. Einen Link zu entfernen macht ein Leck nicht rückgängig, nur die Erneuerung tut das.
- Vereinbaren Sie den Erneuerungsprozess jetzt. Legen Sie fest, wer einen Ersatz anfordert, erstellt und einspielt, ob die Implementierung eine kurze Überlappung erlaubt und wie Sie den neuen Wert testen, bevor Sie den alten stilllegen. Ein bekanntes Verfahren ist besser als ein hektischer Austausch während eines Ausfalls.
- Räumen Sie auf. Sobald der Kunde den Abruf bestätigt, widerrufen Sie temporäre Zugriffe und löschen verstreute Kopien in Entwürfen, Tickets und Notizen. Prüfen Sie die Aufbewahrungsregeln jedes beteiligten Systems. Eine Nachricht aus einer Ansicht zu löschen, entfernt sie selten aus den Backups.
Fehler suchen, ohne das Secret preiszugeben
Ein Problem bei der Übergabe ist kein Grund, das Secret über einen schwächeren Kanal erneut zu senden. Klären Sie zuerst, welcher von drei Fällen vorliegt: Der Kunde kann das Secret nicht abrufen, kann den Endpunkt nicht konfigurieren, oder er erhält Anfragen, kann aber die Signaturen nicht prüfen.
- Abruf fehlgeschlagen oder Zeitfenster abgelaufen. Bestätigen Sie den Empfänger erneut und starten Sie eine neue, kontrollierte Übergabe. Fügen Sie den Wert nicht in ein Ticket ein und bitten Sie den Kunden nicht, seinen Wert zum Vergleich zurückzuschicken.
- Signatur stimmt nicht überein. Fast immer liegt es an den Eingaben der Prüfung: das falsche Secret für diesen Endpunkt, ein Body, der vor dem Hashen umformatiert wurde, oder ein falsch gelesener Header. Lassen Sie den Kunden mit einem bekannten Ereignis über die Testwerkzeuge des Absenders testen.
- Anfragen kommen nie an. Das ist ein Problem der Zustellung oder des Routings, kein Problem des Secrets. Prüfen Sie Zeitstempel, Antwortcodes und die Auswahl des Endpunkts, bevor jemand an eine Erneuerung denkt. Die Webhook-Dokumentation von Stripe ist ein gutes Vorbild dafür, wie man Registrierung des Endpunkts und Zustellung der Ereignisse von der Signaturprüfung trennt.
- Teilen Sie geschwärzte Diagnosedaten. Ereignis-ID, Zeitstempel, Endpunkt und Fehlerkategorie reichen aus. Entfernen Sie das Secret, die vollständige Signatur, wo sie sensibel ist, und private Felder der Payload, und prüfen Sie die Schwärzung, bevor Sie eine Beispielanfrage senden.
Prüfen Sie den Empfänger, übergeben Sie das Secret einmal über einen Kanal, der es wieder vergisst, sorgen Sie dafür, dass es in einem Secrets-Speicher landet, und erneuern Sie es ohne Zögern, wenn es durchgesickert sein könnte. Wie Einmal-Links allgemein in Engineering-Abläufe passen, lesen Sie unter sicheres Teilen von Links für Entwickler.