Zum Hauptinhalt springen

​
Überblick

Sie können Webhooks erstellen, um Benachrichtigungen zu erhalten, wenn bestimmte Ereignisse in Ihrem Konto auftreten. Sie können beispielsweise Webhooks erstellen, um Benachrichtigungen zu erhalten, wenn eine Kampagne erstellt, aktualisiert oder gelöscht wird. Um Benachrichtigungen zu erhalten, müssen Sie die URL angeben, an die die Benachrichtigungen gesendet werden. Wenn ein Ereignis eintritt, erhält Ihre URL eine HTTP-POST-Anfrage mit den Details des Ereignisses. Ihre URL:
  • Muss öffentlich zugänglich sein
  • Muss POST-Anfragen empfangen können
  • Muss einen HTTP-Statuscode 2xx für erfolgreiche Anfragen zurückgeben
Um einen Webhook zu erstellen, müssen Sie die Create Webhook API aufrufen. Sie können das Ereignis angeben, das den Webhook auslöst, indem Sie das channel-Feld verwenden. Sie können nur einen Webhook pro Kanal erstellen.

​
Wiederholungsversuche

Wenn Ihre Webhook-URL zum Zeitpunkt des Ereignisses nicht erreichbar ist, werden wir versuchen, die Anfrage bis zu 5 Mal mit exponentiellem Backoff innerhalb der nächsten Minute erneut zu senden. Wir werden die Anfrage nur für HTTP-Statuscodes 5xx oder 429 wiederholen.

​
Validierung

Um sicherzustellen, dass Ihr Server nur Webhook-Zustellungen verarbeitet, die von Topsort gesendet wurden, und dass die Zustellung nicht manipuliert wurde, sollten Sie die Webhook-Signatur validieren, bevor Sie die Zustellung weiterverarbeiten. Topsort verwendet Ihr Webhook-Secret und die Event-Payload, um eine Signatur zu generieren und diese im HTTP-Header X-TS-Signature-256 für jede Zustellung einzuschließen. Sie können Ihr Webhook-Secret beim Erstellen eines Webhooks angeben. Wenn Sie kein Secret angeben, generieren wir eines für Sie. Sie müssen Ihr Secret sicher auf Ihrem Server speichern. Topsort verwendet den HMAC-Hexadezimal-Digest, um den Hash der Signatur zu berechnen. Die Signatur beginnt immer mit sha256=. Sie sollten überprüfen, dass die Signatur korrekt ist, indem Sie den Hash auf Ihrer Seite neu berechnen und ihn mit der Signatur im X-TS-Signature-256-Header vergleichen.

​
Beispiel für Signaturverifizierung

import hmac
import hashlib

secret = "my-webhook-secret"
request = ... # incoming request from the webhook delivery

signature = hmac.new(
    key=secret.encode(),
    msg=await request.body(),
    digestmod=hashlib.sha256,
).hexdigest()

expected_signature = "sha256=" + signature
incoming_signature = request.headers["X-TS-Signature-256"]
if not hmac.compare_digest(incoming_signature, expected_signature):
    # The signature is not valid, do not process the delivery
else:
    # The signature is valid, process the delivery