ERP-Integration: Bewerberablauf

Überblick

Dieser Leitfaden beschreibt, wie ein ERP- oder Lohnsystem einen Bewerber aus talent.Flow übernimmt und anschließend weiterpflegt. Der Ablauf folgt durchgehend einem Muster:

Ereignis → Referenz → Abruf → Pflege.

talent.Flow meldet per Webhook, dass etwas passiert ist, und liefert dazu die Referenz auf den betroffenen Datensatz. Die Daten selbst holt sich das ERP anschließend gezielt ab.

Kurzfassung: Einmalig Webhook für das Ereignis Candidate marked as hired registrieren, im Empfänger sofort mit 200 antworten, den Bewerber über den im Payload mitgelieferten Endpunkt abrufen und danach über die Änderungs- und Ergänzungsendpunkte pflegen. Kein Polling.

Kein Polling. Die Bewerberänderungs-Endpunkte (/candidates/export/candidates/changes/…) sind für den Erstabgleich und für Wiederherstellung gedacht — nicht als Dauerbetrieb. Wer sie im Minutentakt abfragt, erzeugt Last ohne Mehrwert: die Webhooks liefern dasselbe Ereignis früher und mit weniger Aufrufen.

Der Ablauf im Bild

sequenceDiagram
    participant U as Anwender in talent.Flow
    participant TF as talent.Flow
    participant ERP as Ihr ERP-System
    U->>TF: Bewerber auf „Eingestellt" setzen
    TF->>ERP: POST auf Ihre Webhook-URL (Ereignis 1377)
    ERP-->>TF: 200 OK
    Note over ERP: Verarbeitung asynchron anstoßen
    ERP->>TF: GET /v3/candidates/export/candidates/{entityId}
    TF-->>ERP: Bewerberdatensatz
    Note over ERP: Übernahme, Anreicherung, Abgleich
    ERP->>TF: PUT / POST / DELETE zur Pflege
    TF-->>ERP: 200 OK

Schritt 1: Webhook registrieren

Ein Webhook wird immer pro Ereignis registriert:

curl -X POST https://api.talent360.io/v3/webhooks/subscribe \
  -H "Authorization: Bearer IHR_ACCESS_TOKEN" \
  -H "User-Agent: Mozilla/5.0 (Kundenname)" \
  -H "Content-Type: application/json" \
  -d '{"event": 1377, "url": "https://erp.example.com/hooks/talent360"}'

Zweck	Endpunkt
Webhook registrieren	`POST /v3/webhooks/subscribe`
Registrierung aufheben	`POST /v3/webhooks/unsubscribe`
Registrierungen prüfen	`GET /v3/webhooks/subscriptions`
Verfügbare Ereignistypen	`GET /v3/webhooks/event/types`

Ereignisse rund um den Bewerber

Id	Ereignis	Cloud-Event	Bedeutung
`1377`	Candidate marked as hired	`io.talent360.candidatemovedtohired`	Der Bewerber wurde auf „Eingestellt" gesetzt
`1378`	Candidate marked as placed	`io.talent360.candidatemovedtoplaced`	Der Bewerber wurde auf „Vermittelt" gesetzt
`1423`	Candidate created	`io.talent360.candidatecreated`	Ein Bewerber wurde angelegt
`1424`	Candidate application created	`io.talent360.candidateapplicationcreated`	Zu einem Bewerber wurde eine Bewerbung angelegt

Für die Übernahme in ein Lohn- oder ERP-System ist in aller Regel 1377 das richtige Ereignis. 1423 und 1424 feuern deutlich früher im Prozess und liefern Datensätze, die fachlich noch nicht übernahmereif sind.

Die vollständige und verbindliche Liste aller Ereignisse liefert GET /v3/webhooks/event/types.

Regeln für die Registrierung

Ein Webhook-Endpunkt darf für mehrere Ereignisse registriert werden.
Auf ein Ereignis dürfen mehrere Endpunkte registriert werden.
Die Kombination aus URL und Ereignis muss eindeutig sein.
Der Zielendpunkt muss öffentlich per POST erreichbar sein.

Datenformat wählen

Wert	Format
`1482`	Standard (talent360)
`1483`	Azure Cloud Event
`0`	nicht festgelegt

curl -X PUT https://api.talent360.io/v3/webhooks/settings/eventdatatype/1482 \
  -H "Authorization: Bearer IHR_ACCESS_TOKEN" \
  -H "User-Agent: Mozilla/5.0 (Kundenname)"

Die Einstellung gilt mandantenweit, nicht pro Registrierung. Gesetzt wird sie über PUT /v3/webhooks/settings/eventdatatype/{type}, geprüft über GET /v3/webhooks/settings.

Schritt 2: Das Ereignis entgegennehmen

Ihr Endpunkt erhält einen POST mit diesen Feldern:

Feld	Bedeutung
`id`	Eindeutige Id dieses Ereignisses (GUID) — als Idempotenzschlüssel verwenden
`eventId`	Id des Ereignistyps, z. B. `1377`
`event`	Textuelle Beschreibung des Ereignisses
`entityId`	Id des Datensatzes, für den das Ereignis ausgelöst wurde
`endpoint`	Referenzendpunkt, über den dieser Datensatz abgerufen wird
`endpointMethod`	HTTP-Methode des Referenzendpunkts
`eventDateUtc`	Zeitpunkt der Auslösung (UTC)
`additionalData`	Ereignisabhängige Zusatzdaten

Nutzen Sie endpoint und endpointMethod aus dem Payload, statt den Abrufpfad fest zu verdrahten. Damit übersteht Ihre Integration Pfadänderungen der API, ohne dass Sie ausrollen müssen.

Antworten Sie sofort mit 200. Jede Antwort, die kein 200 ist, erhöht den Fehlerzähler dieser Registrierung. Stoßen Sie die eigentliche Verarbeitung asynchron an — eine langlaufende Übernahme im Webhook-Handler ist der häufigste Grund für pausierte Registrierungen.

Fehlerschwelle: Jede Registrierung hat einen eigenen Fehlerzähler. Ein erfolgreicher Aufruf setzt ihn zurück, 10 Fehler in Folge pausieren die Registrierung — der Endpunkt wird dann nicht mehr aufgerufen. Reaktiviert wird durch erneutes POST /webhooks/subscribe. Die Ereignisse gehen dabei nicht verloren: sie werden weiter protokolliert und lassen sich nachträglich abrufen (siehe Ausfall und Wiederherstellung).

Das Feld id ist die Ereignis-GUID. Speichern Sie sie und verwerfen Sie Wiederholungen mit bereits bekannter id — damit ist Ihre Verarbeitung idempotent, auch wenn dasselbe Ereignis mehrfach zugestellt wird.

Schritt 3: Den Bewerber abrufen

curl -X GET https://api.talent360.io/v3/candidates/export/candidates/4711 \
  -H "Authorization: Bearer IHR_ACCESS_TOKEN" \
  -H "User-Agent: Mozilla/5.0 (Kundenname)" \
  -H "Accept: application/json"

4711 ist die entityId aus dem Ereignis.

Zweck	Endpunkt
Volldatensatz des Bewerbers	`GET /v3/candidates/export/candidates/{candidateId}`

Bewerber tragen keine externe Id. Anders als Firmen (dort gibt es importExternalId) hat der Bewerberdatensatz kein Feld, in dem Ihr ERP seine eigene Id ablegen kann. Führen Sie deshalb im ERP eine Zuordnungstabelle talent.Flow-candidateId ↔ ERP-Id und schlüsseln Sie darüber. Ein Abgleich über Name oder E-Mail ist nicht zuverlässig.

Schritt 4: Daten ändern

Teil-Update, kein Full-Replace. Für PUT /candidates/{candidateId} gilt: Nur die übermittelten Felder werden geändert. Sie müssen also nicht den kompletten Datensatz zurückschicken — senden Sie ausschließlich, was sich tatsächlich geändert hat.

Zweck	Endpunkt
Stammdaten ändern	`PUT /v3/candidates/{candidateId}`
Status setzen (archivieren, ablehnen, qualifizieren, einstellen)	`PUT /v3/candidates/{id}/status`
Arbeitsvertrag pflegen	`PUT /v3/candidates/{candidateId}/workcontract`
Ende der Einsatzzeit setzen	`PUT /v3/candidates/{candidateId}/endofoperation`
Sprache ändern	`PUT /v3/candidates/{candidateId}/languages/{languageId}`

Fehlerantworten

Status	Bedeutung
`200`	Erfolg — die Antwort enthält die `id` des geänderten Bewerbers
`400`	Ungültige Anfrage oder Validierungsfehler
`404`	Bewerber nicht gefunden

Der Fehlerkörper ist bei 400 und 404 identisch aufgebaut:

{
  "messageGuid": "3f8b1c2e-...",
  "message": "Beschreibung des Fehlers",
  "validationErrors": []
}

Protokollieren Sie messageGuid mit. Bei einer Supportanfrage lässt sich der Vorgang darüber eindeutig zuordnen — ohne diese Kennung bleibt nur die Suche über Zeitstempel.

Schritt 5: Daten ergänzen

Ergänzungen laufen nicht über das Stammdaten-Update, sondern über eigene Endpunkte je Objekt:

Bereich	Endpunkte
Kontaktwege	`POST /v3/candidates/{id}/email` · `…/sms` · `…/whatsapp`
Profil	`…/professions` · `…/keywords` · `…/qualifications` · `…/languages` · `…/driverslicences` · `…/pictures`
Werdegang	`…/resume/jobs` · `…/resume/professioneducations` · `…/resume/schooleducations` · `…/resume/educations`
Dokumente	`POST /v3/candidates/{candidateId}/documents/cv` · `…/documents/other` · `…/documents/{documentCategory}`
Kommunikation	`POST /v3/candidates/{candidateId}/communications` · `…/communications/{id}/attachments`

Wenn Ihr System Bewerber auch anlegt: Ein über POST /v3/candidates erzeugter Bewerber wird in talent.Flow erst angezeigt, wenn zu ihm mindestens eine Bewerbung existiert. Legen Sie deshalb im selben Vorgang eine Bewerbung an (POST /v3/candidates/{id}/apply), sonst entsteht ein für Anwender unsichtbarer Datensatz.

Zweck	Endpunkt
Bewerber anlegen	`POST /v3/candidates`
Bewerbung zum Bewerber anlegen	`POST /v3/candidates/{id}/apply`

Schritt 6: Daten löschen

Für vier Unterobjekte des Bewerbers gibt es DELETE-Endpunkte:

Objekt	Endpunkt
Führerschein	`DELETE /v3/candidates/{candidateId}/driverslicences/{driversLicenseId}`
Sprache	`DELETE /v3/candidates/{candidateId}/languages/{languageId}`
Beruf	`DELETE /v3/candidates/{id}/professions/{professionId}`
Qualifikation	`DELETE /v3/candidates/{id}/qualifications/{qualificationId}`

Weiter reicht das Löschen nicht. Für den Bewerber selbst, für Kontaktwege (E-Mail, SMS, WhatsApp), den Werdegang, Keywords, Dokumente und das Profilbild gibt es keine Löschendpunkte. Soll ein Bewerber aus dem operativen Blick verschwinden, führt der Weg über den Status: PUT /v3/candidates/{id}/status.

Ausfall und Wiederherstellung

Fällt Ihr ERP aus oder wurde die Registrierung wegen der Fehlerschwelle pausiert, sind die Ereignisse nicht verloren — talent.Flow protokolliert sie weiter.

curl -X POST https://api.talent360.io/v3/webhooks/protocol \
  -H "Authorization: Bearer IHR_ACCESS_TOKEN" \
  -H "User-Agent: Mozilla/5.0 (Kundenname)" \
  -H "Content-Type: application/json" \
  -d '{
        "eventDateFromUtc": "2026-07-30T00:00:00Z",
        "eventDateToUtc":   "2026-07-31T00:00:00Z",
        "eventTypes":       [1377]
      }'

Der Endpunkt dazu: POST /v3/webhooks/protocol. Optional lässt sich zusätzlich auf eine entityId einschränken. Jeder Protokolleintrag trägt seinen Zustellstatus:

Wert	Status	Bedeutung
`130`	Transfered	Der Webhook wurde erfolgreich aufgerufen
`131`	Failed	Der Webhook hat kein `200` geliefert — Grund steht in `sendStatusReason`
`132`	Skipped	Die Registrierung ist wegen zu vieler Fehler pausiert

Empfohlenes Vorgehen nach einer Störung

Zeitraum der Störung bestimmen.
Protokoll für diesen Zeitraum und die abonnierten Ereignisse abrufen.
Alle Einträge mit sendStatusId 131 oder 132 verarbeiten — über die bereits gespeicherten Ereignis-ids Doppelverarbeitungen ausschließen.
Registrierung mit erneutem POST /v3/webhooks/subscribe reaktivieren, falls sie pausiert war.

Empfehlungen im Überblick

Auf Ereignisse reagieren statt zu pollen — Änderungsendpunkte nur für Erstabgleich und Wiederherstellung.
Im Webhook-Handler sofort 200 antworten, Verarbeitung asynchron anstoßen.
Abrufpfad aus endpoint und endpointMethod des Payloads nehmen, nicht fest verdrahten.
Ereignis-id als Idempotenzschlüssel speichern.
Zuordnungstabelle für Bewerber-Ids führen — der Bewerber trägt keine externe Id.
Bei Änderungen nur geänderte Felder senden.
messageGuid aus Fehlerantworten mitprotokollieren.
Access Token zwischenspeichern (siehe Authentifizierung) — ein Token pro Tag, nicht pro Webhook-Ereignis.

Checkliste vor dem Go-Live

Webhook-URL ist öffentlich per POST erreichbar und antwortet in jedem Fall mit 200.
Registrierung für Ereignis 1377 ist angelegt und über GET /v3/webhooks/subscriptions geprüft.
Das Ereignisdatenformat ist gesetzt und entspricht dem, was Ihr Empfänger erwartet.
Wiederholte Zustellungen desselben Ereignisses werden verworfen.
Ein Wiederherstellungslauf über /webhooks/protocol ist implementiert und einmal getestet.
Der Fall „Registrierung pausiert" ist überwacht — sonst bleibt der Ausfall unbemerkt.