Was ist ein Webhook?
Ein Webhook ermöglicht es Ihnen, benachrichtigt zu werden, wenn bestimmte System-Aktionen auftreten, indem eine von Ihnen bereitgestellte URL aufgerufen wird. Webhooks werden auch als „URL-Callbacks” oder „HTTP-Push-Aufrufe” bezeichnet. Ihre URL muss SSL verwenden und mit HTTPS beginnen.Webhook-Aktionen
Sehen Sie sich die verfügbaren Aktionen für Webhooks an.
Ayrshare-Webhooks verstehen
Webhooks werden nach der jeweiligen Aktion kategorisiert und auf Ebene des Primary Profiles oder des User Profiles registriert. Alle Updates für das Primary Profile oder das User Profile werden zuerst an den für das User Profile registrierten Webhook gesendet. Verfügt das User Profile über keinen registrierten Webhook, wird das Update an den für das Primary Profile registrierten Webhook gesendet. Zum Beispiel:- Wenn ein User Profile einen registrierten Social-Action-Webhook hat und TikTok trennt, wird die für das User Profile registrierte Social-Action-Webhook-URL aufgerufen. Der Webhook des Primary Profiles wird nicht aufgerufen.
- Wenn ein User Profile TikTok trennt und keinen registrierten Social- Action-Webhook hat, das Primary Profile aber über einen registrierten Webhook verfügt, wird die für das Primary Profile registrierte Social-Action-Webhook-URL aufgerufen.
Einen Webhook registrieren
Registrieren Sie einen Webhook, indem Sie eine Endpunkt-URL und den Aktionstyp an den POST-Endpunkt/hook/webhook übergeben. Wenn die Aktion eintritt, wird eine HTTP POST-Nachricht an die angegebene URL gesendet.
Z. B. Registrieren einer URL, um über den Status eines geplanten Beitrags benachrichtigt zu werden.
Die Webhook-Endpunkt-URL sollte keine Weiterleitungen verwenden und muss die endgültige Ziel-URL sein.
Wenn Sie nur den Webhook des Primary Profiles registrieren, erben die User Profiles automatisch den Webhook des Primary Profiles.
Um für jedes User Profile einen eigenen Webhook zu haben, müssen Sie einen Webhook für jedes User Profile registrieren.
Nachdem Ihr Webhook den
HTTP POST empfangen hat, muss Ihr Server mit
einem HTTP-Status 200 antworten, um den Aufruf als erfolgreich zu markieren. Wenn Ihr
Server nicht innerhalb von 15 Sekunden antwortet, wird der Versuch als
fehlgeschlagen protokolliert und wiederholt. Antworten Sie sofort, sobald Sie
die Anfrage empfangen, und führen Sie Ihre Verarbeitung asynchron durch. Ein
Timeout ist keine Ablehnung. Wenn Ihr Handler die Arbeit also abschließt, aber
zu spät antwortet, sorgt die Wiederholung dafür, dass Sie sie zweimal verarbeiten.Webhook-Wiederholungen
Ob eine fehlgeschlagene Zustellung wiederholt wird, hängt davon ab, wie sie fehlgeschlagen ist. Jeder Wiederholungsversuch trägt dieselbehookId. Die Nutzlast wird für jeden Versuch neu erzeugt, sodass timeStamp — und die Signatur darüber — abweichen können.
Wird wiederholt — vorübergehende Fehler. Eine 429-, 408- oder 425-Antwort, jedes 5xx, eine Zeitüberschreitung oder eine abgebrochene Verbindung erhält bis zu 9 Zustellversuche über etwa eine Stunde — die erste Zustellung plus 8 Wiederholungen. Schlägt es danach weiterhin fehl, wird die Zustellung nach einem abnehmenden Zeitplan erneut versucht — etwa 5 Minuten, 30 Minuten, 2 Stunden und 12 Stunden später. Eine Zustellung kann daher bis zu etwa 16 Stunden nach dem ursprünglichen Ereignis eintreffen.
Wird nicht wiederholt — Ablehnungen. Jede andere 4xx-Antwort, etwa 400, 401, 403, 404 oder 410, gilt beim ersten Versuch als endgültig. Sie besagt, dass die Anfrage selbst abgelehnt wurde, und eine Wiederholung kann daran nichts ändern.
Zustellungssemantik und Idempotenz
Ayrshare stellt Webhooks mindestens einmal zu. Gelegentliche Duplikate sind normaler Betrieb, kein Fehler. Jeder Consumer benötigt Idempotenz als dauerhafte Eigenschaft. Duplikate treten in zwei verschiedenen Formen auf, und jede erfordert einen anderen Schlüssel:hookId identifiziert eine Zustellung eines Ereignisses. Sie ist bei jeder Wiederholung dieser Zustellung identisch, sodass eine darauf basierende Beanspruchung Wiederholungen sicher macht. Eine neue Benachrichtigung desselben zugrunde liegenden Ereignisses trifft jedoch mit einer neuen hookId ein, sodass hookId allein diesen Fall nicht erkennt.
Empfohlenes Empfängermuster:
- Zuerst antworten. Geben Sie sofort
2xxzurück und verarbeiten Sie dann asynchron. Ein Timeout ist keine Ablehnung. Wenn Sie die Arbeit abschließen, aber zu spät antworten, wird das Ereignis erneut gesendet. - Beanspruchen Sie
hookIdatomar in dem Moment, in dem die Anfrage eintrifft. Eine eindeutige Einschränkung, einINSERT ... ON CONFLICT DO NOTHINGoder einSET NX, nicht eine Read-then-Write-Prüfung. Zwei Versuche können gleichzeitig eintreffen, und eine Check-then-Act-Absicherung lässt beide durch. - Beanspruchen Sie zusätzlich einen eigenen Schlüssel, der aus der Nutzlast erstellt wird, damit eine zweite Benachrichtigung mit einer neuen
hookIdweiterhin erkannt wird. Beimessagesfunktioniertidin Kombination mitsubActiongut. - Führen Sie dann die Arbeit aus und halten Sie beide Beanspruchungen lange genug, um das Wiederholungsfenster und eine spätere erneute Benachrichtigung abzudecken. Da ein Wiederholungsversuch bis zu etwa 16 Stunden später eintreffen kann, halten Sie Ihre Beanspruchungen mindestens 24 Stunden. Eine Beanspruchung, die früher abläuft, erkennt einen späten Wiederholungsversuch nicht, und Sie verarbeiten dasselbe Ereignis zweimal.
Die
id der Nutzlast ist für sich genommen nicht bei jedem Ereignistyp
eindeutig. Dieselbe Nachrichten-ID tritt bei Bearbeitungen und Reaktionen
erneut auf, und messageRead-Nutzlasten enthalten keine id. Kombinieren Sie
sie daher mit subAction, anstatt sie allein zu verwenden.Header mit Zustellungsmetadaten
Jede Zustellung enthält zwei Header, die die jeweilige Übertragung identifizieren, sodass Sie ein Original von einer Wiederholung unterscheiden können:X-Ayrshare-Delivery-Attempt ist beim ersten Senden 0 und wird bei jeder Wiederholung um eins erhöht, sodass jeder Wert über 0 bedeutet, dass wir diese Zustellung bereits mindestens einmal gesendet haben. Behandeln Sie ihn als unbegrenzten Zähler und nicht als festen Satz von Werten. Die Anzahl der Wiederholungen ist ein betrieblicher Aspekt, der sich ändern kann. X-Ayrshare-Delivery-Id ist für jeden Versuch eindeutig. Nennen Sie ihn dem Support, und er identifiziert den genauen Zustellungsdatensatz.
Diese identifizieren die Übertragung; hookId identifiziert das Ereignis. Deduplizieren Sie anhand von hookId, nicht anhand der Delivery-ID. Die Delivery-ID ist per Design bei jedem Versuch anders, sodass nichts jemals als Duplikat erkannt würde.
Webhook-Sicherheit
Sie können zusätzliche Sicherheit hinzufügen, indem Sie eine HMAC-Authentifizierung als HTTP-Request-Header setzen. Dies wird häufig verwendet, um Replay-Angriffe zu verhindern. Ayrshare verwendet HMAC-SHA256, um den Body der Nachricht zu hashen, und fügt diesen Hash zusammen mit dem UNIX-Zeitstempel in den Header des POST ein.X-Authorization-Content-SHA256 mit dem HMAC-SHA256 des POST-Bodys vergleichen. Das Signing Secret gilt profilweit: ein Secret pro User Profile, das über alle Webhook-Aktionen dieses Profils hinweg verwendet wird, sodass das Setzen für eine Aktion es für alle Aktionen dieses Profils ändert. Multi-Profile-Konten verwalten ein separates Secret pro Profil (adressieren Sie ein Profil über den Profile-Key-Header).