Wofür werden Webhooks verwendet?

Webhooks ermöglichen es Ihnen:

Echtzeit-Benachrichtigungen über Ereignisse in Kickscale zu erhalten.
Prozesse zu automatisieren, z. B. das Aktualisieren externer Systeme bei neuen Ereignissen.
API-Abfragen zu reduzieren, wodurch Zeit und Ressourcen gespart werden.

Ein Beispiel: Wenn ein Meeting in Kickscale analysiert wurde, können Sie einen Webhook einrichten, um die Ereignisdaten an Ihr System zu senden.

Einrichtung von Webhooks

Sie können Webhooks direkt in Ihren Arbeitsbereich-Einstellungen konfigurieren. So richten Sie sie ein:

Navigieren Sie zur Webhook-Konfiguration
- Gehen Sie zu Einstellungen > Arbeitsbereich > API.
- Suchen Sie den Abschnitt Webhooks und klicken Sie auf Webhooks verwalten.
Webhook einrichten
- Geben Sie im angezeigten Dialog die URL Ihres Systems ein, das die Webhook-Anfragen verarbeitet.
- Aktivieren Sie die Ereignisse, für die Sie Benachrichtigungen erhalten möchten.
Webhook speichern
- Nach dem Speichern wird Ihr persönliches Webhook-Secret angezeigt.
  ⚠️ Wichtig: Speichern Sie dieses Secret an einem sicheren Ort, da es nur einmal angezeigt wird.
Secret aktualisieren (falls erforderlich)
- Um ein neues Secret zu generieren, öffnen Sie den Dialog Webhooks verwalten und nutzen Sie die Option zum Aktualisieren.

Webhook-Anfragen verifizieren

Aus Sicherheitsgründen enthält jede Webhook-Anfrage von Kickscale eine Signatur im Header, um die Echtheit der Anfrage zu überprüfen. Hier ein Beispiel, wie Sie die Signatur in Ihrer Anwendung verifizieren können:

const signature = request.headers['kickscale-signature-hash'];
const timestamp = request.headers['kickscale-signature-timestamp'];

const data = `${timestamp}${rawBody}`;

const hmac = crypto.createHmac('sha256', Buffer.from(webhookSecret, 'hex'));

const calculatedSignature = hmac.update(Buffer.from(data, 'utf-8')).digest('hex');

const valid = crypto.timingSafeEqual(Buffer.from(signature, 'hex'), Buffer.from(calculatedSignature, 'hex'));

Zusätzliche Ressourcen

Antworttypen und Definitionen

Meeting Analysiert:

{
   eventType: "meeting_analyzed";
   meeting: MeetingDTO;
}

Detaillierte Informationen zu den Antworttypen finden Sie in unserer Swagger-Dokumentation.

Tipps und Best Practices

Verifizieren Sie immer die Webhook-Signatur, um sicherzustellen, dass die Anfrage echt ist.
Verwenden Sie eine sichere HTTPS-Endpunkt-URL für Ihren Webhook.
Speichern Sie Ihr Webhook-Secret sicher, da es nach Schließen des Dialogs nicht mehr abrufbar ist.
Überprüfen Sie regelmäßig Ihre Webhook-Einstellungen, um sicherzustellen, dass sie aktuell sind.

Fehlerbehebung

Ich habe mein Webhook-Secret nicht gespeichert. Was kann ich tun?

Sie können im Dialog Webhooks verwalten ein neues Secret generieren.

Mein System erhält keine Webhook-Anfragen.

Überprüfen Sie, ob Ihre Webhook-URL korrekt und öffentlich zugänglich ist.
Stellen Sie sicher, dass das gewünschte Ereignis aktiviert ist.
Prüfen Sie, ob Ihr System die Anfragen mit den richtigen Headern und dem korrekten Payload-Format verarbeitet.

Wie kann ich meine Webhook-Integration testen?

Verwenden Sie ein Testtool wie Postman oder ein eigenes Skript, um Beispiel-Payloads an Ihren Endpunkt zu senden. Details zu den Payload-Formaten finden Sie in der Swagger-Dokumentation.

Wenn Sie Fragen haben oder Unterstützung benötigen, kontaktieren Sie uns gerne unter support@kickscale.com.