Wie kann ich 12Build-Webhooks einrichten?

Was finden Sie in diesem Artikel?

• Zusammenfassung: Die Funktionsweise von Webhooks in 12Build.

• Voraussetzungen und Zielgruppe: Was Sie für die Konfiguration benötigen.

• Die Einrichtung: So erstellen Sie einen neuen Endpunkt.

• Die Webhook-Nachricht: Informationen zu Format und JSON-Struktur.

• Verfügbare Objekte: Welche Daten Sie abrufen können.

• Relationale Daten: Eigene Daten über die API verwalten.

• Häufig gestellte Fragen (FAQ): Fragen zu Limits und Inaktivität.

• Fehlerbehebung: Vorgehensweise bei fehlgeschlagenen Zustellungen.

Zusammenfassung

Webhooks ermöglichen es, Änderungen an 12Build-Daten direkt an externe Anwendungen zu „pushen“. Anstatt Daten manuell abzurufen, sendet 12Build eine Benachrichtigung an einen von Ihnen festgelegten Endpunkt, sobald eine relevante Änderung stattfindet.

Voraussetzungen und Zielgruppe

Diese Funktion richtet sich an Administratoren oder Entwickler, die 12Build mit anderen Systemen verknüpfen möchten.

• Beziehungen: Es werden nur Benachrichtigungen für Nachunternehmer gesendet, zu denen eine Beziehung besteht (gekennzeichnet durch einen grünen, goldenen oder schwarzen Stern).

• Limit: Die Webhook-Funktion funktioniert bis zu maximal 3.000 Beziehungen.

Die Einrichtung

Sie konfigurieren die Webhooks in den allgemeinen Einstellungen Ihrer Organisation.

1. Navigieren Sie zu den Einstellungen des Unternehmensprofils.

2. Navigieren Sie zum Abschnitt „Webhooks“.

3. Erstellen Sie einen neuen Webhook und geben Sie den gewünschten Endpunkt (die URL Ihrer externen Anwendung) an.

4. Wählen Sie die spezifischen Objekte und Ereignisse aus, für die Sie eine Benachrichtigung erhalten möchten.

Die Webhook-Nachricht

Wenn eine Systemänderung Ihren Einstellungen entspricht, wird eine JSON-Nachricht gesendet.

• Zustellgarantie: Bei einem fehlgeschlagenen Zustellversuch (keine HTTP-2xx-Antwort oder ein Timeout) versucht 12Build maximal dreimal, die Nachricht erneut zu senden.

• Inaktiv: Wenn ein Webhook 3 Tage lang keine erfolgreiche Zustellung verzeichnet hat, wird er automatisch auf „inaktiv“ gesetzt.

• Struktur: Der Body enthält JSON-Daten mit Feldern wie webhookId, action, object, timestamp, sowie sowohl die aktuelle (current) als auch die vorherigen (previous) Daten des Objekts.

Verfügbare Objekte

Derzeit können Sie Webhooks für die folgenden fünf Objekte einrichten:

• Company

• Unternehmensbeziehung

• Unternehmensbeziehung

• Dokument

• Nachricht

Beziehungsdaten

Es ist möglich, eigene relationale Daten zu Beziehungen hinzuzufügen, die ausschließlich für den eigenen Gebrauch bestimmt sind.

• Verwaltung: Derzeit gibt es in 12Build keine Oberfläche zur Verwaltung dieser Daten.

• API: Verwenden Sie die API-Funktionen, um relationale Daten zu verwalten über:

  • getRelations

  • addRelationData

  • removeRelationData

  • updateRelationData

Häufig gestellte Fragen (FAQ)

Frage: Warum erhalte ich keine Benachrichtigungen von bestimmten Nachunternehmern? Antwort: Webhooks senden nur Daten von Unternehmen, die als Kontakt markiert sind (Favoriten mit einem Stern). Überprüfen Sie, ob der betreffende Nachunternehmer einen Stern-Status hat.

Frage: Was passiert, wenn mein Server vorübergehend offline ist? Antwort: 12Build versucht bis zu viermal, die Nachricht zu versenden. Beachten Sie, dass der Webhook nach 3 Tagen ohne erfolgreiche Zustellung automatisch deaktiviert wird.

Fehlerbehebung

• Symptom: Der Webhook ist auf „inaktiv“ gesetzt.

  • Ursache: In den letzten 3 Tagen wurde keine erfolgreiche Verbindung zu Ihrem Endpunkt hergestellt (keine HTTP-200-Serie-Antwort).

  • Lösung: Überprüfen Sie die Erreichbarkeit und die Logs Ihres Endpunkts und aktivieren Sie den Webhook erneut in den Einstellungen Ihres Unternehmensprofils.