Ein Webhook in Bitrix24 ist eine Möglichkeit, das Portal mit einem externen Dienst zu verbinden, ohne eine App zu schreiben: Ein eingehender Webhook gibt einem externen System einen URL-Schlüssel zum Aufruf der REST-API des Portals, ein ausgehender bringt Bitrix24 dazu, bei einem Ereignis selbst Ihre URL zu kontaktieren. Das ist der schnellste Weg der Integration, doch er hat Grenzen, über die die Hilfe schweigt. Sehen wir uns beide Typen an, das Anlegen, die Beschränkungen und das dritte Szenario, das am häufigsten gebraucht wird: ein Webhook aus einem Geschäftsprozess.

Worin unterscheidet sich ein eingehender Webhook von einem ausgehenden?

Ein eingehender ist eine URL der Form https://portal.bitrix24.de/rest/1/schlüssel/, über die ein externer Dienst Methoden der REST-API aufruft: einen Lead erstellen, einen Deal aktualisieren, die Aufgabenliste abrufen. Die Rechte werden beim Anlegen festgelegt (nur CRM, nur Aufgaben usw.), die Aktionen werden im Namen des Mitarbeiters ausgeführt, dem der Schlüssel gehört. Ein ausgehender ist umgekehrt: Sie geben die URL Ihres Handlers und ein Ereignis an (Lead erstellt, Deal aktualisiert), und Bitrix24 sendet dorthin bei jedem Auslösen einen POST. Die Kombination beider Typen ergibt eine bidirektionale Integration: Der ausgehende meldet „ein Kontakt ist aufgetaucht", der externe Dienst reichert die Daten an und schreibt sie per eingehendem Webhook zurück.

Wo erstellt man einen Webhook und was ist zu prüfen?

Bereich „Für Entwickler" (in älteren Menüs — „Apps") → „Sonstiges" → „Eingehender Webhook" / „Ausgehender Webhook". Für den eingehenden: Wählen Sie die Zugriffsrechte nach dem Minimalprinzip — ein Schlüssel mit den Rechten „CRM + alles andere" gibt bei einem Leck dem Angreifer die gesamte Datenbank preis; kopieren Sie die URL mit dem Schlüssel und bewahren Sie sie wie ein Passwort auf. Für den ausgehenden: Geben Sie die Handler-URL und das App-Token zur Authentizitätsprüfung an — der Handler muss das Token abgleichen, sonst kann jeder, der die Adresse erfährt, gefälschte Ereignisse senden. Die Verfügbarkeit von Webhooks hängt vom Tarif ab: Bei einem Teil der Tarife ist ein Bitrix24.Market-Abonnement erforderlich.

Welche Beschränkungen haben Webhooks?

Drei, an denen Integrationen scheitern. Das Anfragelimit: Die REST-API akzeptiert etwa zwei Anfragen pro Sekunde und Portal, bei Überschreitung — der Fehler QUERY_LIMIT_EXCEEDED; Massenoperationen werden in Batch-Aufrufe verpackt. Ein ausgehender Webhook wiederholt die Zustellung nicht: War Ihr Handler drei Sekunden nicht erreichbar, ist das Ereignis verloren — Bitrix24 versucht es nicht erneut. Und ein ausgehender Webhook trägt ein Minimum an Daten (ID und Ereignistyp) — für die Felder muss man trotzdem per eingehendem Webhook in die REST-API gehen. Deshalb ist ein „zuverlässiger Bus auf Basis ausgehender Webhooks" ein Mythos: Für kritische Ereignisse braucht es eine Zustellung mit Bestätigung und Wiederholungen.

Wie sendet man einen Webhook aus einem Geschäftsprozess?

Ein häufiges Szenario, das es in den Standardaktionen nicht gibt: beim Übergang eines Deals auf eine Phase einen externen Dienst anstoßen — ein Warenwirtschaftssystem, ein Lager, einen Messenger-Bot. Das decken zwei Roboter von Roboteka ab. „HTTP-Anfrage" sendet einen GET oder POST mit Headern und Body und gibt die Antwort und den Statuscode in Prozessvariablen zurück — für synchrone Szenarien „gefragt und Antwort erhalten" (die Antwort wird vom Roboter „Wert aus JSON nach Pfad extrahieren" zerlegt). „Ausfallsicherer Webhook" — für das Szenario „unbedingt zustellen": Er wiederholt den Versand bei Nichterreichbarkeit des Empfängers, und das Ereignis geht nicht verloren, während der externe Dienst neu startet. Faustregel: Brauchen Sie eine Antwort hier und jetzt — HTTP-Anfrage; brauchen Sie eine Zustellgarantie für die Benachrichtigung — ausfallsicherer Webhook.

Der Webhook funktioniert nicht: Checkliste

Der eingehende gibt einen Fehler zurück: Prüfen Sie die Rechte des Schlüssels (die Methode erfordert einen Scope, der fehlt), die Aktivität des Mitarbeiters, dem der Schlüssel gehört (ein entlassener Mitarbeiter = ein toter Schlüssel) und das Anfragelimit. Der ausgehende kommt nicht an: Prüfen Sie, dass der Handler schnell mit Code 200 antwortet (eine langsame Antwort wertet Bitrix24 als Fehler), dass die URL von außen erreichbar ist (kein localhost, nicht von einer Firewall geschlossen) und dass das Ereignis tatsächlich das richtige ist — „Deal-Aktualisierung" löst nicht beim Phasenwechsel im Aufgaben-Kanban aus. Und denken Sie an das Fehlen von Wiederholungen: Lag der Empfänger lahm, muss das Ereignis von Hand wiederhergestellt werden — oder von Anfang an per ausfallsicherem Webhook aus dem Prozess gesendet werden.

Fazit

Webhooks sind der günstigste Weg der Integration mit Bitrix24: der eingehende zur Steuerung des Portals von außen, der ausgehende für Signale nach außen, und aus Geschäftsprozessen heraus die Roboter mit HTTP-Anfrage und Zustellgarantie aus dem Roboteka-Katalog. Fehlt das benötigte Szenario — beschreiben Sie die Aufgabe, wir bauen den Roboter kostenlos.