Skip to main content
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).
Das Klartext-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.
Wenn Sie erneut rotieren, während noch ein Grace-Fenster offen ist, wird das gerade ersetzte Secret zum neuen vorherigen Secret, und ein frisches 24-Stunden-Fenster beginnt. Es wird immer nur ein vorheriges Secret zur Zeit vorgehalten.

Signaturen während des Grace-Fensters verifizieren

Außerhalb eines Grace-Fensters tragen signierte Zustellungen die Standard-Header (siehe Webhook-Sicherheit):
Während des 24-Stunden-Fensters nach einer Rotation listet der neue Header 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.
Jeder Wert in 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.
Dass eine Übereinstimmung mit irgendeiner gelisteten Signatur ausreicht, macht die Rotation ausfallfrei: Ein Empfänger, der noch mit dem alten Secret konfiguriert ist, matcht 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
Berechnen Sie den HMAC immer über die rohen Request-Body-Bytes, genauso wie empfangen – nicht über ein neu serialisiertes JSON-Objekt. Neuserialisierung kann Whitespace oder Schlüsselreihenfolge verändern und die Verifizierung brechen. Verwenden Sie einen konstanten Zeitvergleich (etwa crypto.timingSafeEqual), um Timing-Angriffe zu vermeiden.
Falls bei einer Zustellung der Datensatz des aktuellen Secrets fehlt, wird die Zustellung unsigniert (ohne Signatur-Header) fortgesetzt statt zu scheitern. Fehlt nur der Datensatz des vorherigen Secrets, wird die vorherige Signatur übersprungen und die aktuelle Signatur wird weiterhin in beiden Headern ausgeliefert.