Verwenden Sie diese Anleitung, um Fin's Integrationsfehler mit webhooks in Echtzeit an Ihre eigenen Systeme zu senden. Wenn Sie einen webhook hinzufügen, sendet Fin bei jedem neuen Fehler in den Error logs eine signierte POST-Anfrage an Ihre URL, damit Sie diese an Ihre Alarm-, Ticket- oder Überwachungssysteme weiterleiten können.
Hinweis: Error-Logs-webhooks sind für Fin für Plattform-Workspaces verfügbar, die mit Salesforce, HubSpot, Freshdesk oder Zendesk verbunden sind.
Bevor Sie beginnen
Sie benötigen die Berechtigung Apps und Integrationen verwalten, um den webhook hinzuzufügen, zu testen oder zu entfernen. Ohne diese Berechtigung können Sie im Webhook-Bereich Berechtigung anfordern auswählen.
Ihr Endpunkt muss über HTTPS öffentlich erreichbar sein. Beim Speichern sendet Fin eine HEAD-Anfrage, um die Erreichbarkeit zu prüfen.
Ihr Endpunkt sollte innerhalb von 7 Sekunden einen 2xx-Statuscode zurückgeben.
So fügen Sie einen webhook hinzu
Gehen Sie zu Einstellungen > Error logs (unter Integrationen).
Klicken Sie oben rechts auf der Seite auf Webhook.
Geben Sie im Feld Webhook-URL Ihren Endpunkt ein, zum Beispiel
your-server.example.com/error-logs. Das Präfixhttps://wird automatisch hinzugefügt.Wählen Sie Speichern. Sie sehen „Webhook gespeichert“, wenn die URL validiert wurde.
(Optional) Kopieren Sie das unter der URL angezeigte Signing secret. Sie verwenden es, um zu überprüfen, dass die Anfragen von Fin stammen.
Wählen Sie Test, um ein Testereignis an Ihren Endpunkt zu senden. Sie sehen „Test gesendet“, wenn Ihr Endpunkt erfolgreich antwortet.
Hinweis: Der Test sendet ein
ping-Ereignis, keinen Error-Log. Stellen Sie sicher, dass Ihr Endpunkt beide Themen akzeptiert (siehe Beispiele unten).
Was Fin an Ihren webhook sendet
Fin sendet für jeden neuen Fehler, der in den Error logs erscheint, eine Anfrage. Wenn derselbe Fehler innerhalb einer Stunde für dasselbe Gespräch erneut auftritt, wird er möglicherweise nur einmal protokolliert und gesendet.
Jede Anfrage ist eine POST mit einem JSON-Body und diesen Headern:
Content-Type: application/json
X-Hub-Signature: die Anfragesignatur (siehe So überprüfen Sie die Signatur).
Intercom-Webhook-Subscription-ID: die ID Ihres webhook-Abonnements.
Beispiel für eine Error-Log-Nutzlast
Die Fehlerdetails befinden sich in data.item. Das Thema ist immer error_log.created.
{
"type": "notification_event",
"app_id": "abc123de",
"topic": "error_log.created",
"id": "notif_1a2b3c4d",
"created_at": 1762430400,
"data": {
"type": "notification_event_data",
"item": {
"type": "error_log",
"id": "123",
"app_id": "abc123de",
"created_at": 1762430400,
"environment": {
"type": "environment",
"id": "456",
"name": "acme.my.salesforce.com",
"is_production": true
},
"error_code": "INVALID_FIELD",
"error_message": "No such column 'InvalidField' on entity 'Case'",
"request_status": 400,
"request_method": "POST",
"request_path": "/services/data/v58.0/sobjects/Case",
"object_type": "Case",
"api_type": "salesforce_rest_api",
"product_feature": "salesforce_cases",
"integration_type": "salesforce_cases",
"conversation_id": "789"
}
}
}
Error-Log-Felder
id: die ID des Error-Log-Eintrags.
app_id: Ihre Fin-Workspace-ID.
created_at: Zeitpunkt des Fehlers als Unix-Zeitstempel in Sekunden.
environment: die verbundene helpdesk-Umgebung, z. B. Ihre Salesforce-Organisation oder Zendesk-Subdomain. Kann null sein.
error_code: der von Ihrem helpdesk zurückgegebene Fehlercode, z. B. INVALID_FIELD.
error_message: die vom helpdesk zurückgegebene Fehlermeldung.
request_status, request_method und request_path: HTTP-Status, Methode und Pfad der fehlgeschlagenen Anfrage.
object_type: das betroffene helpdesk-Objekt, z. B. Case oder Knowledge__kav.
api_type: die helpdesk-API, die Fin aufgerufen hat, z. B. salesforce_rest_api, hubspot_rest_api, freshdesk_rest_api oder zendesk_rest_api.
product_feature: die betroffene Fin-Funktion, z. B. salesforce_cases, fin_messenger, knowledge_import oder historical_conversations_import.
integration_type: die Fin-Integration, aus der der Fehler stammt, z. B. salesforce_cases oder zendesk_tickets.
conversation_id: das zugehörige Fin-Gespräch, falls vorhanden. Kann null sein.
Hinweis: Diese Felder entsprechen denen im Fehlerdetails-Bereich der Error logs. Um einen bestimmten Fehlercode zu verstehen und zu beheben, siehe Fin for Salesforce: Häufige Integrationsfehler beheben.
Wichtig: error_message und request_path stammen direkt von Ihrem helpdesk und können Datensätze wie Feldwerte oder IDs enthalten. Speichern Sie die Nutzlasten sicher.
Beispiel für eine Test-Nutzlast
{
"type": "notification_event",
"topic": "ping",
"data": {
"type": "notification_event_data",
"item": {
"type": "ping",
"message": "This is a ping notification test message."
}
}
}
So überprüfen Sie die Signatur
Jede Anfrage enthält einen X-Hub-Signature-Header. Dieser ist ein HMAC-SHA1 des rohen Anfragebodys, signiert mit Ihrem Signing secret, im Format sha1=<hex digest>.
So überprüfen Sie eine Anfrage:
Berechnen Sie ein HMAC-SHA1 des rohen Anfragebodys, bevor Sie das JSON parsen, mit Ihrem Signing secret als Schlüssel.
Fügen Sie dem Hex-Digest das Präfix sha1= hinzu.
Vergleichen Sie es mit dem X-Hub-Signature-Header mit einem zeitkonstanten Vergleich. Lehnen Sie die Anfrage ab, wenn sie nicht übereinstimmen.
Zum Beispiel in Ruby:
expected = "sha1=" + OpenSSL::HMAC.hexdigest("SHA1", signing_secret, raw_body)
valid = Rack::Utils.secure_compare(expected, request.headers["X-Hub-Signature"])Wichtig: Halten Sie Ihr Signing secret geheim. Das Anzeigen oder Kopieren wird im Aktivitätsprotokoll Ihres Workspaces aufgezeichnet.
Zustellung und Wiederholungen
Eine Zustellung gilt als erfolgreich, wenn Ihr Endpunkt einen 2xx-Statuscode zurückgibt. Fin folgt keinen Weiterleitungen, verwenden Sie daher die endgültige URL Ihres Endpunkts.
Wenn Ihr Endpunkt eine Zeitüberschreitung oder einen Fehler zurückgibt, versucht Fin die Zustellung automatisch erneut.
Wenn Ihr Endpunkt 410 Gone zurückgibt, stellt Fin die Zustellung sofort ein.
Fin kann dasselbe Ereignis mehrmals senden. Verwenden Sie die oberste ID des Ereignisses, um Duplikate zu ignorieren.
Fin kann Ereignisse außer der Reihenfolge zustellen. Verwenden Sie created_at, um sie zu sortieren.
Fin sendet pro Fehler eine Anfrage, daher kann ein Ausfall in Ihrem helpdesk viele Anfragen in kurzer Zeit senden. Antworten Sie schnell und verarbeiten Sie Ereignisse im Hintergrund.
Webhook-Statusmeldungen
Wenn Zustellungen fehlschlagen, zeigt der Webhook-Bereich eine dieser Meldungen an:
Pause: „Ihr Endpunkt gibt Fehler zurück, daher sind Zustellungen pausiert. Wir versuchen es automatisch erneut.“ Keine Aktion erforderlich, wenn das Problem vorübergehend ist.
Ausgesetzt: „Ihr Endpunkt hat weiterhin Fehler zurückgegeben, daher sind Zustellungen ausgesetzt.“ Beheben Sie Ihren Endpunkt und wählen Sie dann erneut Speichern, um die Verbindung wiederherzustellen.
Deaktiviert: „Ihr Endpunkt hat 410 Gone zurückgegeben, daher wurden die Zustellungen gestoppt.“ Wählen Sie erneut Speichern, um die Verbindung wiederherzustellen.
Von Fin gestoppt: „Fin hat die Zustellungen an diesen webhook gestoppt.“ Kontaktieren Sie den Support, um sie wieder aufzunehmen.
So entfernen Sie einen webhook
Gehen Sie zu Einstellungen > Error logs und wählen Sie Webhook.
Wählen Sie das Papierkorbsymbol neben der URL.
Wählen Sie Webhook entfernen, um zu bestätigen.
Fin stellt das Senden neuer Error logs an diese URL ein. Bereits unterwegs befindliche Logs können noch ankommen. Sie können jederzeit einen webhook erneut hinzufügen. Dabei wird ein neues Signing secret erstellt, das Sie in Ihrem Endpunkt aktualisieren müssen.
FAQs
Kann ich Error logs an mehr als eine URL senden?
Kann ich Error logs an mehr als eine URL senden?
Noch nicht. Jeder Workspace kann einen Error-Logs-webhook haben.
Kann ich auswählen, welche Fehler gesendet werden?
Kann ich auswählen, welche Fehler gesendet werden?
Nein. Fin sendet jeden neuen Fehler, der in den Error logs erscheint. Sie können in Ihrem eigenen System nach Feldern wie product_feature, api_type oder error_code filtern.
Sendet Fin vergangene Fehler, wenn ich einen webhook hinzufüge?
Sendet Fin vergangene Fehler, wenn ich einen webhook hinzufüge?
Nein. Es werden nur Fehler gesendet, die nach dem Speichern des webhooks protokolliert werden.
Warum hat der Test keinen Error log gesendet?
Warum hat der Test keinen Error log gesendet?
Die Schaltfläche Test sendet ein ping-Ereignis, um zu prüfen, ob Ihr Endpunkt erreichbar ist. Echte Error logs verwenden das Thema error_log.created.
Kann ich das Signing secret ändern oder neu generieren?
Kann ich das Signing secret ändern oder neu generieren?
Das Secret bleibt während der Einrichtung des webhooks gleich. Um ein neues Secret zu erhalten, entfernen Sie den webhook und fügen ihn erneut hinzu.

