Webhooks
Signing Secret rotieren
Rotieren Sie Ihr Webhook-Signing-Secret sicher mit einem 24-Stunden-Dual-Signing-Grace-Fenster
POST
Überblick
Ayrshare signiert jede Webhook-Zustellung mit einem HMAC-SHA256 des Payloads unter Verwendung Ihres Signing Secrets, damit Ihr Empfänger bestätigen kann, dass eine Zustellung tatsächlich von Ayrshare stammt. Wie die Verifizierung funktioniert, sehen Sie unter Webhook-Sicherheit. Durch das Rotieren Ihres Signing Secrets können Sie es regelmäßig oder umgehend austauschen, wenn Sie vermuten, dass es kompromittiert wurde. Damit die Rotation sicher ist, öffnet Ayrshare nach jeder Rotation ein 24-Stunden-Grace-Fenster, in dem Zustellungen mit beiden, dem bisherigen und dem neuen Secret, signiert werden. So können Sie Ihren Empfänger in Ihrem eigenen Tempo aktualisieren, ohne eine einzige Zustellung zu verlieren oder abzulehnen – dasselbe Muster, das auch Stripe und GitHub verwenden.Das Signing Secret gilt profilweit: Es gibt ein Secret pro User Profile (UID),
und es signiert jede Webhook-Aktion, die dieses Profil registriert hat. Es gibt kein
Signing Secret pro Aktion – das Setzen oder Rotieren des Secrets ändert es für alle
Aktionen dieses Profils gleichzeitig.
Über das Dashboard rotieren
Sie können Ihr Signing Secret auf der Webhooks-Seite im Developer Dashboard setzen oder rotieren. Das Panel Signing Secret erscheint oberhalb Ihrer Webhook-Liste, sobald das Profil mindestens einen registrierten Webhook besitzt.1
Signing-Secret-Panel öffnen
Öffnen Sie die Webhooks-Seite. Wenn noch kein Secret konfiguriert ist, zeigt das Panel No signing secret configured mit einer Schaltfläche Set Signing Secret. Ist bereits eines konfiguriert, zeigt es Signing secret configured mit einer Schaltfläche Rotate.
2
Setzen oder Rotieren
Klicken Sie auf Set Signing Secret (erstmalig) oder Rotate (bestehendes Secret). Ein Modal öffnet sich mit einem starken, zufällig generierten und bereits sichtbaren Secret. Sie können es Copyieren, ein neues Regeneraten oder paste my own umschalten, um Ihren eigenen Wert anzugeben.
3
Bestätigen
Kopieren Sie das Secret an einen sicheren Ort – es wird nur einmal angezeigt und kann nicht erneut aus der UI abgerufen werden – und bestätigen Sie dann das Absenden. Ein Erfolgs-Toast erscheint und das Panel wird aktualisiert.
4
Ihren Empfänger aktualisieren
Bei einer Rotation (nicht bei erstmaligem Setzen) zeigt das Panel eine aktive Grace-Window-Anzeige und die Rotate-Schaltfläche ist deaktiviert, bis das Fenster schließt. Sie haben 24 Stunden Zeit, das neue Secret auf Ihrem Empfänger auszurollen.
Über die API rotieren
Rotieren (oder setzen) Sie das Signing Secret mit einem einzigen Aufruf. Dabei wird ein neues Secret erzeugt, die Secret-Referenz des Profils darauf umgestellt und – falls ein bestehendes Secret vorhanden war – das ersetzte Secret als vorheriges Secret mit einer Ablaufzeit von 24 Stunden vermerkt.Header-Parameter
Body-Parameter
string
erforderlich
Der neue Wert des Signing Secrets. Jeder nicht leere String wird akzeptiert. Wir empfehlen einen langen, zufälligen Wert mit hoher Entropie (zum Beispiel 32 zufällige Bytes als base64url kodiert).
secret wird niemals in der Antwort zurückgegeben und niemals geloggt. Die Antwort enthält die clientseitige refId (einen Hash der UID), niemals die UID selbst. Der Profile-Key-Header ist optional und begrenzt die Rotation bei Multi-Profile-Konten auf ein einzelnes User Profile.
Ein fehlendes oder leeres secret gibt einen gemappten Fehler zurück (code: 101, „Missing/incorrect parameter”) mit HTTP-Status 400, und Ihr aktuelles Secret bleibt unverändert. Ein erstmaliges Setzen über die API (kein bestehendes Secret) legt das Secret an, ohne dass ein vorheriges Secret erfasst wird und ohne Grace-Fenster.
Sichere Rotationsprozedur
Dank des 24-Stunden-Grace-Fensters gibt es keine zwingende Reihenfolge – Ihr Empfänger funktioniert die ganze Zeit weiter. Die empfohlene Reihenfolge lautet:1
Secret rotieren
Rotieren Sie über das Dashboard oder die API. Ayrshare beginnt sofort damit, Zustellungen mit beiden Secrets zu signieren – dem bisherigen und dem neuen.
2
Empfänger aktualisieren
Rollen Sie das neue Secret innerhalb von 24 Stunden auf Ihrem Webhook-Empfänger aus, damit dieser gegen den neuen Wert verifiziert.
3
Fenster schließen lassen
Nach 24 Stunden entfernt Ayrshare das vorherige Secret automatisch und signiert nur noch mit dem neuen Secret. Auf Ihrer Seite ist keine weitere Aktion nötig.
Signaturen während des Grace-Fensters verifizieren
Außerhalb eines Grace-Fensters tragen signierte Zustellungen die Standard-Header (siehe Webhook-Sicherheit):X-Authorization-Content-SHA256-V2 beide Signaturen, aktuelle zuerst, kommagetrennt:
X-Authorization-Content-SHA256 bleibt unverändert: Er trägt aus Gründen der
Rückwärtskompatibilität immer den einzelnen HMAC des aktuellen Secrets. Doppelte
Signaturen erscheinen nur im neuen Header X-Authorization-Content-SHA256-V2.X-Authorization-Content-SHA256-V2 ist mit einem Scheme-Tag versehen. v1= bezeichnet eine HMAC-SHA256-Signatur, die genauso berechnet wird wie X-Authorization-Content-SHA256. Der -V2-Header ist immer vorhanden, wann immer eine Zustellung signiert wird – er trägt mindestens v1=<current-sig> –, sodass Sie sich als Empfänger auf ihn als stabilen Vertrag verlassen können.
So verifizieren Sie eine Zustellung während (oder außerhalb) einer Rotation:
1
HMAC berechnen
Berechnen Sie den HMAC-SHA256 des rohen Request-Bodys mit Ihrem lokal konfigurierten Signing Secret.
2
Gegen jede gelistete Signatur vergleichen
Lesen Sie
X-Authorization-Content-SHA256-V2, splitten Sie an Kommas, entfernen Sie das v1=-Präfix von jedem Wert und akzeptieren Sie die Zustellung als authentisch, wenn Ihr berechneter HMAC mit irgendeiner gelisteten v1=-Signatur übereinstimmt.v1=<previous-sig>, während ein bereits auf das neue Secret aktualisierter Empfänger v1=<current-sig> matcht – beide sind während des gesamten Fensters erfolgreich.
Beispiel für die Empfänger-Verifizierung
Node.js
