Webhooks – Übersicht

Was sind Webhooks?

Ein Webhook ist eine Nachricht, die automatisch zwischen Anwendungen gesendet wird, wenn ein bestimmtes Ereignis eintritt. Webhooks eignen sich ideal, um Anwendungen zu verbinden und Abläufe zu automatisieren. Mit Role.so können Sie Bewerberdaten – unabhängig davon, ob ein Kandidat Interesse gezeigt oder abgelehnt hat – nahtlos an jede Plattform senden, die Webhooks unterstützt, einschließlich Make, Zapier und weiterer Dienste.

Anwendungsfälle und Beispiele

Sie können Ihren Ablauf für jedes Szenario automatisieren und anpassen:

Von interessierten Kandidaten übermittelte Kontaktdaten an eine Google-Tabelle senden
Einem Kandidaten, der Interesse an einer Stelle gezeigt hat, automatisch eine SMS senden
Eine Benachrichtigung in Slack senden, wenn ein Kandidat Interesse zeigt oder eine Stelle ablehnt
Kandidatendaten in Ihrem bevorzugten Bewerbermanagementsystem speichern

Ereignisse

Beim Erstellen eines Webhooks können Sie zwischen zwei Ereignistypen wählen: Interested und Declined. Diese Ereignisse entsprechen direkt den beiden Formularen, die in jedem Kandidatenpaket vorhanden sind. Sobald ein Formular übermittelt wurde, senden wir eine Nachricht an alle Ihre aktiven Webhooks, die diesem Ereignistyp entsprechen.

Daten

Je nach Ereignistyp (interested oder declined) senden wir eine feste Datenstruktur. Sie können diese Daten verwenden, um Automatisierungen in Ihren Anwendungen zu erstellen und Ihren Ablauf zu erweitern.

Daten bei Interesse

{
  "contract_version": 1, // 📦 Version des Webhook-Vertrags
  "event_id": "a9f9f96a-0b5b-418a-ac3b-2b316d24695f", // 🪪 Eindeutige Kennung
  "action": "user_interested", // 🔔 Aktionstyp
  "event_timestamp": "2025-02-28T19:08:47.859Z", // 🗓️ Datum als ISO-Zeichenfolge
  "source": "web_form", // 🌐 Ereignisquelle
  "source_url": "https://role.so/packs/demo", // 🔌 Link zum Kandidatenpaket, in dem das Ereignis aufgetreten ist
  "payload": {
    "role": "Software Engineer", // 💼 Rolle, wie sie im Kandidatenpaket konfiguriert ist
    "company": "Acme Inc", // 🏢 Unternehmen, wie es im Kandidatenpaket konfiguriert ist
    "user_details": {
      "name": "Jane Doe", // 👤 Feld für den Namen
      "email": "hello@example.com", // ✉️ Feld für die E-Mail-Adresse
      "phone": "07900000000", // 📞 Feld für die Telefonnummer
      "website": "https://linkedin.com", // 🌐 Feld für die Website-URL
      "attachments": [
        "https://role.so/mock_webhook_file_1.pdf",
        "https://role.so/mock_webhook_file_2.pdf"
      ], // 🔗 Liste der von den Kandidaten angehängten Dateien
      "custom_answers": [
        {
          "label": "Availability",
          "value": "Immediately"
        }
      ] // 📝 Optionale Antworten auf benutzerdefinierte Fragen
    }
  }
}

Wenn keine Antworten auf benutzerdefinierte Fragen übermittelt werden, wird die Eigenschaft custom_answers aus dem Payload weggelassen und nicht auf null gesetzt. Andere nicht verwendete oder deaktivierte skalare Felder werden als null gekennzeichnet, während attachments immer ein Array ist und bei fehlenden Dateien den Wert [] hat. Wenn im Interesseformular Ihres Kandidatenpakets beispielsweise nur die Felder name und email aktiviert sind, senden wir die folgenden Daten:

{
  // Dieselben Daten wie oben
  "payload": {
    "user_details": {
      "name": "Jane Doe",
      "email": "hello@example.com",
      "phone": null,
      "website": null,
      "attachments": []
    }
  }
}

Daten bei Ablehnung

Die Daten bei einer Ablehnung haben eine ähnliche Struktur wie die Daten bei Interesse:

{
  "event_id": "a9f9f96a-0b5b-418a-ac3b-2b316d24695f", // 🪪 Eindeutige Kennung
  "action": "user_declined", // 🔔 Aktionstyp
  "event_timestamp": "2025-02-28T19:08:47.859Z", // 🗓️ Datum als ISO-Zeichenfolge
  "source": "web_form", // 🌐 Ereignisquelle
  "source_url": "https://role.so/packs/demo", // 🔌 Link zum Kandidatenpaket, in dem das Ereignis aufgetreten ist
  "payload": {
    "role": "Software Engineer", // 💼 Rolle, wie sie im Kandidatenpaket konfiguriert ist
    "company": "Acme Inc", // 🏢 Unternehmen, wie es im Kandidatenpaket konfiguriert ist
    "decline_reasons": ["Salary", "Perks", "Office location"] // 📋 Liste der Ablehnungsgründe
  }
}

Wenn Sie benutzerdefinierte Ablehnungsgründe in Ihrem Formular eingerichtet haben, senden wir stattdessen diese Daten. Wenn Ihre benutzerdefinierten Ablehnungsgründe beispielsweise Reason #1 und Reason #2 lauten, senden wir:

{
  // Dieselben Daten wie oben
  "payload": {
    "decline_reasons": ["Reason #1", "Reason #2"]
  }
}

Häufig gestellte Fragen

Frage: Ist diese Funktion im `Starter`-Tarif verfügbar?

Antwort: Der Zugriff hängt von den Funktionen ab, die in Ihrem aktuellen Tarif enthalten sind. Wenn Ihr Konto über die Webhook-Berechtigung verfügt, können Sie diese Funktion nutzen; andernfalls zeigt das Dashboard die verfügbaren Upgrade-Optionen an.

Frage: Wie viele Webhooks kann ich erstellen?

Antwort: Derzeit können Sie maximal 4 Webhooks erstellen.

Frage: Werden Ereignisse und Benachrichtigungen in Echtzeit gesendet?

Antwort: In den meisten Fällen ja. Es kann jedoch zwischen 1 und 5 Minuten dauern, bis die Daten an Ihre Anwendung gesendet werden.

Frage: Kann ich Testereignisse senden?

Antwort: Ja. Sie können Testbenachrichtigungen senden, um Ihren Ablauf einzurichten, ohne die Statistiken Ihrer Kandidatenpakete zu beeinflussen. Weitere Informationen finden Sie im Hilfeartikel Ein Testereignis senden.

Frage: Wie werden Fehler behandelt?

Antwort: Vorübergehende Fehler wie Netzwerkfehler, Zeitüberschreitungen, HTTP-5xx-Antworten und bestimmte vorübergehende 4xx-Antworten erhalten insgesamt bis zu 8 Zustellversuche: den ersten Versuch plus bis zu 7 Wiederholungen. Dauerhafte Fehler wie ungültige Payloads, durch die Sicherheitsrichtlinie blockierte Endpunkte und andere 4xx-Antworten werden nach dem ersten Versuch beendet. Ein Webhook kann bereits nach einem einzelnen Zustellfehler als fehlerhaft gekennzeichnet werden; eine endgültig fehlgeschlagene Zustellung kann manuell erneut versucht werden. Weitere Informationen finden Sie im Hilfeartikel Webhooks überwachen.

Frage: Was passiert, wenn ein Webhook dauerhaft fehlschlägt? Werde ich benachrichtigt?

Antwort: Nicht direkt. Der Webhook wird jedoch als fehlerhaft gekennzeichnet und mit einem Badge Fehlerhaft versehen. Anhaltende Zustellfehler deaktivieren den Webhook nicht automatisch. Überprüfen Sie den Endpunkt und deaktivieren Sie den Webhook bei Bedarf manuell auf der Webhook-Seite. Weitere Informationen finden Sie im Hilfeartikel Webhooks überwachen.