Webhooks in CentralStationCRM

API Navigation

Allgemeines: Grundlagen Authentifizierung Fehlerbehandlung Datenstruktur

Hauptmodelle: Personen Firmen Angebote Projekte Aufgaben

Sonstiges: Anschriften Kontaktdaten Wichtige Daten Individuelle Felder Positionen Notizen Dateianhänge Tags

Die Kür: Webhooks Nutzer Aktivitäten Filter Gruppen Individuelle Feld Typen

Mit Webhooks können Änderungen abonniert werden, um Echtzeit-Synchronisationen zu anderen Diensten anzustoßen. Wir nutzen Webhooks zum Beispiel, um Änderungen an den Stammdaten von Personen direkt nach der Änderung in das Hilfe System zu synchronisieren. Über die API können Hooks angelegt werden, die je nach Aktivität in CentralStationCRM eine gewünschte URL aufrufen und die Änderung direkt mitsenden.

Webhooks können über die create Route angelegt und über die destroy Route gelöscht werden, wie bei den Personen zu sehen. Jeder Webhook enthält die folgenden Felder:

Feldname Feldtyp Beschreibung
id INTEGER ID des Webhooks (Read only)
model VARCHAR(30) Objekttyp, über den benachrichtigt werden soll (person, company, deal, project) (Pflichtfeld)
event VARCHAR(40) Aktivität in CentralStationCRM (create, update, destroy) (Pflichtfeld)
target_url VARCHAR(190) URL, an die der Webhook geschickt werden soll (Pflichtfeld)
object_type VARCHAR(40) Struktur des Webhooks (nested, flat, api, lean) (Pflichtfeld)
includes TEXT Relevant für die object_types nested und api. Unterobjekte können kommagetrennt angegeben werden, damit diese in den Webhook inkludiert werden (z.B. tags, addrs, historic_events ...)
filter_group_id INTEGER ID einer Filter Gruppe. Wenn gesetzt wird der Webhook nur getriggert, wenn das Objekt in der Filter Gruppe ist

Action: Index

GET /hooks.json

Die INDEX Funktion liefert alle hinterlegten Webhooks.

curl -X GET https://accountname.centralstationcrm.net/api/hooks.json

	[
		{
			hook: {
				id: 1,
				model: "Person",
				event: "update",
				target_url: "https://api.centraldesk.com/...",
				verified: false,
				object_type: "nested",
				hook_type: "url",
				failed: 0,
				failed_at: "",
				created_at: "2017-02-14T17:51:36.000+01:00",
				updated_at: "2017-06-28T15:41:06.000+02:00"
			}
		}
	]
	

Struktur der Webhooks (object_type)

Um die Webhooks möglichst einfach verarbeiten zu können, bieten wir verschiedene Formate an. Diese werden mit dem object_type festgelegt.

  1. nested: Das Objekt wird als Record mitgeschickt. includes Optionen sind möglich. Z.B. {model=>"person", event=>"update", record=> {id: 42, first: 'Axel', addrs: [], tags: []}
  2. flat: Keine Verschachtelung, daher nicht 1:n Daten möglich. Z.B.: {"last_name"=>"von Leitner", "position"=>"CEO", "company"=>"42he", "office_phone"=>"+49-2159-538-1442"}
  3. api: Verhalten identisch zur API. Es kommt z.B. nur person: {name: xy, addrs: []}. includes Optionen sind möglich
  4. lean: Wir versenden nur die Art des Webhooks und die ID des geänderten Objektes. Z.B.: {model: 'person', event: 'create', record_id: 42}