Antwort verknüpfen

Legt ein Webhook im Zielsystem einen neuen Datensatz an, antwortet das System meist mit dessen ID. Mit einer Verknüpfung speichert Centrics diese ID am Datensatz unter external_refs.<Referenz>. In weiteren Webhooks – etwa zum Aktualisieren – adressierst Du den Datensatz im Zielsystem dann mit einem Platzhalter wie {{ contact.external_refs.sevdesk }}.

Verknüpfungen funktionieren für Aufgaben, Protokolle und Kontakte.

Verknüpfung einrichten

1. Öffne im Webhook-Editor den Abschnitt Verknüpfung.
2. Schalte Angelegten Datensatz verknüpfen ein.
3. Wähle unter Referenz, unter welchem Schlüssel die ID gespeichert wird (siehe Referenzen).
4. Trage unter Pfad der ID in der Antwort ein, wo die ID im JSON der Antwort steht. Vorbelegt ist objects.id.
5. Speichere den Webhook.

Den Pfad musst Du nicht raten: Sende in der Vorschau einen Test und klicke in der Antwort auf den Wert mit der ID. Centrics übernimmt seinen Pfad dann automatisch.

Pfad der ID

Der Pfad besteht aus den Schlüsseln bis zur ID, getrennt durch Punkte. Erlaubt sind Buchstaben, Ziffern, _ und -.

Antwort des Zielsystems	Pfad
{"id": 4711}	id
{"objects": {"id": "4711"}}	objects.id
{"data": {"customer": {"id": "4711"}}}	data.customer.id

Die Antwort muss JSON sein. Der Wert am Pfad muss ein einzelner Wert sein (Text oder Zahl) und darf höchstens 64 Zeichen lang sein.

Referenzen

Eine Referenz ist der Schlüssel, unter dem die IDs eines Zielsystems gespeichert werden.

• SevDesk (sevdesk) ist eingebaut und in jedem Account vorhanden. Unter diesem Schlüssel speichert auch der Kontakt-Import die SevDesk-IDs.
• Eigene Referenzen legst Du in der Auswahl Referenz über + Neu anlegen an: Gib einen Namen ein, z. B. „HubSpot CRM“, und klicke auf Anlegen. Aus dem Namen wird der Schlüssel gebildet, hier hubspot_crm (Kleinbuchstaben, Umlaute umschrieben, Leerzeichen als _, höchstens 32 Zeichen). Der Name muss mit einem Buchstaben beginnen.

Referenzen sind dauerhaft

Der Schlüssel einer Referenz kann nach dem Anlegen nicht mehr geändert werden, und Referenzen lassen sich nicht löschen – die gespeicherten IDs hängen an diesem Schlüssel. Wähle den Namen deshalb mit Bedacht.

Regeln der Verknüpfung

• Nur bei Erfolg: Die ID wird nur gespeichert, wenn das Zielsystem mit einem HTTP-Status zwischen 200 und 299 antwortet.
• Nur einmal: Die ID wird nur gesetzt, solange die Referenz am Datensatz noch leer ist. Eine einmal gespeicherte ID wird nie überschrieben.
• Bereits verknüpfte Datensätze werden übersprungen: Hat ein Datensatz für diese Referenz schon eine ID, sendet ein Webhook mit Verknüpfung gar nicht erst. Die Zustellung erscheint im Protokoll als Abgebrochen. So legen z. B. importierte Kontakte, wiederhergestellte Datensätze oder ein Typwechsel keinen zweiten Datensatz im Zielsystem an.
• Kein Speichern bei Tests: Test senden in der Vorschau und Erneut senden im Zustellprotokoll verknüpfen nie. Ereignisse vom Typ „Gelöscht“ verknüpfen ebenfalls nicht.
• Probleme sind Warnungen: Ist die Antwort kein JSON oder steht am Pfad kein Wert, bleibt die Zustellung Erfolgreich – das Zielsystem hat den Datensatz ja angelegt. Im Protokoll steht dann ein Hinweis, warum keine ID gespeichert wurde.
• Keine Kettenreaktion: Das Speichern der ID gilt nicht als Änderung des Datensatzes und löst keinen weiteren Webhook aus.

Verknüpfung nur im Anlege-Webhook

Schalte Angelegten Datensatz verknüpfen nur in dem Webhook ein, der Datensätze im Zielsystem anlegt. In einem Update-Webhook würde die Verknüpfung dafür sorgen, dass genau die bereits verknüpften Datensätze übersprungen werden – also alle, die Du aktualisieren willst.

Fehlgeschlagene Anlage erneut senden

Weil Erneut senden nicht verknüpft, wird bei einer erneut gesendeten Anlage keine ID gespeichert. Prüfe in diesem Fall im Zielsystem, ob der Datensatz angelegt wurde.