Zum Inhalt springen
AurionAI

Entwickler-API: Verwendung und Webhooks

4 Min. LesezeitVon Emmanuel Yazbeck

Die Entwickler-API-Seiten zeigen, wie Programme die AurionAI-API verwenden, und ermöglichen es Ihnen, AurionAI-Ereignisse über Webhooks an Ihre eigenen Systeme zu senden.

Verfügbarkeit: alle Profile. Nur Administratoren.

Voraussetzungen

  • Sie haben die Rolle Eigentümer oder Administrator. Andere Rollen können diese Seiten nicht öffnen.
  • Für Webhooks: eine HTTPS-Adresse auf Ihrer Seite, die POST-Anfragen mit einem JSON-Body akzeptiert.

Entwickler-API-Seiten öffnen

  1. Wählen Sie in der oberen Leiste Ihren Namen oder Ihr Bild aus, um das Benutzermenü zu öffnen.
  2. Wählen Sie Mandanteneinstellungen.
  3. Gehen Sie zur Karte Entwickler-API.
  4. Wählen Sie API-Nutzungsübersicht oder Webhook-Verwaltung.

Die Entwickler-API-Karte auf der Seite „Tenant-Einstellungen".

API-Nutzung überprüfen

Die Seite „API Usage Dashboard" zeigt den Datenverkehr der AurionAI-API für Ihre Organisation.

  1. Wählen Sie unter „Window" die Option „Last 1 day", „Last 7 days" oder „Last 30 days". Der Standardwert ist sieben Tage.
  2. Lesen Sie die vier Gesamtwerte: „Total Requests", „Error Rate", „Rate-Limit Hits" und „Webhook Success".
  3. Lesen Sie „Top API Paths", um zu sehen, welche Adressen am häufigsten aufgerufen werden, einschließlich ihrer Fehler.
  4. Lesen Sie „Daily Trend", um den Datenverkehr pro Tag zu sehen.
  5. Wählen Sie „Refresh", um die neuesten Zahlen zu laden.

Einen Webhook registrieren

  1. Gehen Sie auf der Seite „Webhook Management" zu „Create Subscription".
  2. Geben Sie unter „Target URL" die HTTPS-Adresse Ihres Empfängers ein.
  3. Wählen Sie unter „Events" die Ereignisse aus, die Sie empfangen möchten. Die Ereignisse sind gruppiert: Konversationen, Nachrichten, Kontakte, Tickets, Anrufe, Wissensdatenbank und System.
  4. Wählen Sie „Create webhook".
  5. Ein Dialog zeigt das Signierungsgeheimnis. Wählen Sie „Copy secret" und bewahren Sie das Geheimnis an einem sicheren Ort auf. AurionAI zeigt es nur dieses eine Mal.
  6. Wählen Sie „I have saved my secret".

Der neue Webhook erscheint unter „Subscriptions" mit dem Status „Active".

Eine Webhook-Signatur verifizieren

Jede Zustellung ist eine POST-Anfrage mit einem JSON-Body und diesen Headern:

  • X-Webhook-Event: der Name des Ereignisses, zum Beispiel ticket.created.
  • X-Webhook-Timestamp: der Zeitpunkt der Zustellung.
  • X-Webhook-Signature: die Signatur der Zustellung.

Um zu prüfen, ob eine Zustellung von AurionAI stammt:

  1. Nehmen Sie den Wert von X-Webhook-Timestamp, einen Punkt und den rohen Body der Anfrage, in dieser Reihenfolge.
  2. Berechnen Sie einen HMAC-SHA256 dieses Textes mit Ihrem Signierungsgeheimnis.
  3. Schreiben Sie das Ergebnis in Hexadezimalform und vergleichen Sie es mit X-Webhook-Signature. Akzeptieren Sie die Zustellung nur, wenn sie übereinstimmen.

Einen Webhook testen, pausieren oder löschen

  • Wählen Sie „Send test", um eine Testzustellung zu senden. Ein pausierter Webhook kann keinen Test empfangen.
  • Wählen Sie „Pause", um Zustellungen vorübergehend zu stoppen, und „Resume", um sie wieder zu starten.
  • Wählen Sie „Delete" und bestätigen Sie, um den Webhook zu entfernen.
  • Die Seite listet die neuesten Zustellungen auf, mit ihrem Status, der Anzahl der Versuche und dem HTTP-Status Ihres Empfängers.

Ergebnis

AurionAI sendet jedes ausgewählte Ereignis an Ihre Adresse. Eine Zustellung gilt als erfolgreich, wenn Ihr Empfänger mit einem 2xx-Status antwortet. Andernfalls versucht AurionAI es später erneut, insgesamt bis zu fünf Versuche.

Wenn etwas schiefläuft

  • „Webhook URL is required." Geben Sie die Adresse Ihres Empfängers ein.
  • „Select at least one event to subscribe to." Wählen Sie mindestens ein Ereignis aus.
  • Eine Meldung besagt, dass die Webhook-URL mit https beginnen muss. AurionAI sendet Webhooks nur an HTTPS-Adressen.
  • Eine Meldung besagt, dass die Adresse blockiert ist oder nicht aufgelöst werden kann. AurionAI lehnt private, lokale und unbekannte Adressen ab. Verwenden Sie eine öffentliche Adresse, die im DNS aufgelöst wird.
  • Die Signatur stimmt nicht überein. Verwenden Sie den rohen Body wie empfangen, vor jeglichem Parsen. Verwenden Sie das Geheimnis dieses Webhooks. Wenn Sie das Geheimnis verloren haben, löschen Sie den Webhook und erstellen Sie ihn neu.
  • Zustellungen schlagen fehl. Überprüfen Sie den HTTP-Status in der Zustellungsliste. Ihr Empfänger muss mit einem 2xx-Status antworten.
  • „No webhooks configured" unter „Webhook Success". Ihre Organisation hat noch keinen Entwickler-Webhook.

Verwandte Artikel

Kommen Sie nicht weiter? Stellen Sie eine Anfrage oder .