Webhooks

Outbound-Webhooks ermöglichen es Ihnen, Echtzeit-HTTP-POST-Benachrichtigungen zu erhalten, wenn Ereignisse in Ihrem Projekt auftreten. Pro

Überblick

Webhooks liefern einen JSON-Payload an eine beliebige HTTPS-Endpoint-URL, die Sie konfigurieren, sobald ein bestimmtes Ereignis in Ihrem Projekt eintritt. Jedes Webhook kann sich für eines oder mehrere der folgenden Ereignisse registrieren:

Webhooks gelten für einzelne Projekte. Jedes Projekt hat seinen eigenen Satz von Webhook-Endpunkten mit unabhängigen Konfigurationen und Signaturschlüsseln.

Einen Webhook konfigurieren

1. Öffnen Sie die Einstellungen Ihres Projekts
2. Scrollen Sie zum Abschnitt Outbound-Webhooks
3. Klicken Sie auf Webhook hinzufügen
4. Geben Sie Ihre Endpoint-URL ein (muss in Produktion HTTPS sein)
5. Wählen Sie aus, für welche Ereignisse Sie sich registrieren möchten
6. Klicken Sie auf Speichern

Nach dem Speichern wird ein Signaturschlüssel einmalig angezeigt. Kopieren Sie ihn sofort — er kann später nicht mehr abgerufen werden. Sie können ihn jederzeit über das Aktionsmenü des Webhooks neu generieren.

Webhook-Signaturen überprüfen

Jede Webhook-Zustellung enthält einen X-SupDesk-Signature-Header mit einer HMAC-SHA256-Signatur des Request-Bodys. So überprüfen Sie einen Webhook:

1. Berechnen Sie HMAC-SHA256(Ihr_Signaturschlüssel, Rohdaten_des_Requests)
2. Vergleichen Sie das Ergebnis mit dem Hex-Wert im X-SupDesk-Signature-Header (nach dem Präfix sha256=)
3. Verwenden Sie einen Vergleich mit konstanter Zeit, um Timing-Angriffe zu verhindern

Node.js

import { createHmac, timingSafeEqual } from "crypto";
 
function verifyWebhook(secret, body, signature) {
  const expected = createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  const sig = signature.replace("sha256=", "");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

Python

import hmac
import hashlib
 
def verify_webhook(secret: str, body: bytes, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    sig = signature.removeprefix("sha256=")
    return hmac.compare_digest(expected, sig)

Ruby

require "openssl"
 
def verify_webhook(secret, body, signature)
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, body)
  sig = signature.sub("sha256=", "")
  Rack::Utils.secure_compare(expected, sig)
end

Einen Webhook testen

Klicken Sie auf die Schaltfläche Test neben einem Webhook, um einen Beispiel-Payload an seinen Endpoint zu senden. Der Test-Payload hat "event": "test" und ein data.message-Feld. Verwenden Sie ein Tool wie webhook.site , um die zugestellte Anfrage zu überprüfen.

Zustellungsprotokoll

Das Zustellungsprotokoll zeigt die letzten 50 Zustellungsversuche für jeden Webhook, einschließlich:

• Ereignis — welches Ereignis zugestellt wurde
• Status — success oder failed
• Antwortcode — HTTP-Statuscode des Endpoints
• Versuche — Anzahl der Zustellungsversuche (einschließlich Wiederholungen)
• Zeit — wann der Zustellungsversuch unternommen wurde

Wiederholungsverhalten

Wenn eine Webhook-Zustellung fehlschlägt (5xx-Antwort oder Netzwerk-Timeout), wiederholt SupDesk bis zu 3 Mal mit exponentiellem Backoff:

Client-Fehler (4xx) werden nicht wiederholt — sie weisen auf ein dauerhaftes Problem mit der Endpoint-Konfiguration hin.

Plananforderungen

Outbound-Webhooks sind auf Pro- und Team-Plänen verfügbar.