Zum Hauptinhalt springen
Header

​
Überblick

Webhooks in Twenty ergänzen die API, indem sie Echtzeit-Benachrichtigungen an Ihre eigenen Anwendungen senden, wenn bestimmte Ereignisse in Ihrem CRM auftreten. Anstatt die API kontinuierlich auf Änderungen zu prüfen, können Sie Webhooks einrichten, damit Twenty Daten an Ihr System sendet, sobald bestimmte Ereignisse auftreten (zum Beispiel, wenn ein neuer Datensatz erstellt oder ein bestehender aktualisiert wird). So bleiben externe Systeme sofort und effizient mit Twenty synchron. Mit Webhooks sendet Twenty eine HTTP-POST-Anfrage an eine von Ihnen angegebene URL, die Details zum Ereignis enthält. Sie können diese Daten dann in Ihrer Anwendung verarbeiten (z. B. um Ihre externe Datenbank zu aktualisieren, Workflows auszulösen oder Benachrichtigungen zu senden).

​
Einrichten eines Webhooks

Um einen Webhook in Twenty zu erstellen, verwenden Sie die APIs & Webhooks-Einstellungen in Ihrer Twenty-App:
  1. Navigieren Sie zu Einstellungen: Gehen Sie in Ihrer Twenty-Anwendung zu Einstellungen → APIs & Webhooks.
  2. Create a Webhook: Under Webhooks click on + Create webhook.
  3. URL eingeben: Geben Sie die Endpunkt-URL auf Ihrem Server an, an die Twenty Webhook-Anfragen senden soll. Dies sollte eine öffentlich zugängliche URL sein, die POST-Anfragen verarbeiten kann.
  4. Speichern: Klicken Sie auf Speichern, um den Webhook zu erstellen. Der neue Webhook ist sofort aktiv.
Sie können mehrere Webhooks erstellen, wenn Sie verschiedene Ereignisse an unterschiedliche Endpunkte senden müssen. Jeder Webhook ist im Wesentlichen ein Abonnement für alle relevanten Ereignisse (zu diesem Zeitpunkt sendet Twenty alle Ereignistypen an die angegebene URL; das Filtern spezifischer Ereignistypen kann in der Benutzeroberfläche konfigurierbar sein). Wenn Sie jemals einen Webhook entfernen müssen, können Sie ihn auf derselben Einstellungsseite löschen (wählen Sie den Webhook und wählen Sie löschen).

​
Ereignisse und Nutzlasten

Sobald ein Webhook eingerichtet ist, sendet Twenty eine HTTP-POST-Anfrage an Ihre angegebene URL, wann immer ein Auslöserereignis in Ihren CRM-Daten eintritt. Häufige Ereignisse, die Webhooks auslösen, umfassen:
  • Datensatz erstellt: z. B. wird eine neue Person hinzugefügt (person.created), ein neues Unternehmen wird erstellt (company.created), eine Notiz wird erstellt (note.created) usw.
  • Datensatz aktualisiert: z. B. werden die Informationen einer bestehenden Person aktualisiert (person.updated), ein Unternehmensdatensatz wird bearbeitet (company.updated) usw.
  • Datensatz gelöscht: z. B. wird eine Person oder ein Unternehmen gelöscht (person.deleted, company.deleted).
  • Andere Ereignisse: Falls zutreffend, andere Objekt-Ereignisse oder benutzerdefinierte Auslöser (zum Beispiel, wenn Aufgaben oder andere Objekte aktualisiert werden, würde ähnliche Ereignistypen verwendet, wie task.created, note.updated, usw.).
Die Webhook-POST-Anfrage enthält eine JSON-Nutzlast in ihrem Body. Die Nutzlast enthält in der Regel mindestens zwei Dinge: den Ereignistyp und die Daten zu diesem Ereignis (oft den Datensatz, der erstellt/aktualisiert wurde). Beispielsweise könnte ein Webhook für eine neu erstellte Person eine Nutzlast senden wie: 
{
  "event": "person.created",
  "data": {
    "id": "abc12345",
    "firstName": "Alice",
    "lastName": "Doe",
    "email": "alice@example.com",
    "createdAt": "2025-02-10T15:30:45Z",
    "createdBy": "user_123"
  },
  "timestamp": "2025-02-10T15:30:50Z"
}
In diesem Beispiel:
  • "event" gibt an, was passiert ist (person.created).
  • "data" enthält die Details des neuen Datensatzes (die gleichen Informationen, die Sie erhalten würden, wenn Sie diese Person über die API anfordern).
  • "timestamp" ist wann das Ereignis stattgefunden hat (in UTC).
Ihr Endpunkt sollte bereit sein, solche JSON-Daten über POST zu empfangen. Typischerweise werden Sie das JSON parsen, den "event"-Typ betrachten, um zu verstehen, was passiert ist, und dann die "data" entsprechend verwenden (z. B. einen neuen Kontakt in Ihrem System erstellen oder einen bestehenden aktualisieren). Hinweis: Es ist wichtig, mit einem 2xx HTTP-Status von Ihrem Webhook-Endpunkt aus zu antworten, um den erfolgreichen Empfang zu bestätigen. Wenn der Twenty-Webhooksender keine 2xx-Antwort erhält, kann er die Zustellung als fehlgeschlagen betrachten. (In Zukunft könnte die Wiederholungslogik versuchen, fehlgeschlagene Webhooks erneut zu senden. Streben Sie also immer an, so schnell wie möglich nach der Datenverarbeitung ein 200 OK zurückzugeben.)

​
Webhook-Validierung

Um die Sicherheit Ihrer Webhook-Endpunkte zu gewährleisten, fügt Twenty eine Signatur im Header X-Twenty-Webhook-Signature hinzu. Diese Signatur ist ein HMAC SHA256-Hash der Anfrage-Nutzlast, berechnet mit Ihrem Webhook-Geheimnis. Um die Signatur zu validieren, müssen Sie:
  1. Das X-Twenty-Webhook-Timestamp-Header-Zeitstempel, einen Doppelpunkt und den JSON-String der Nutzlast miteinander verketten
  2. Den HMAC SHA256-Hash mit Ihrem Webhook-Geheimnis als Schlüssel berechnen ()
  3. Das resultierende Hex-Digest mit dem Signaturheader vergleichen
Hier ist ein Beispiel in Node.js: 
const crypto = require("crypto");
const timestamp = "1735066639761";
const payload = JSON.stringify({...});
const secret = "your-secret";
const stringToSign = `${timestamp}:${JSON.stringify(payload)}`;
const signature = crypto.createHmac("sha256", secret)
  .update(stringToSign)
  .digest("hex");