Ein Webhook in Bitrix24 (Alaio) 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.

Wer darf Webhooks anlegen, und lässt sich das einschränken?

Jeder Mitarbeiter, der den Bereich für Entwickler öffnen kann, nicht nur Administratoren. Das REST-Modul behält nur einige fertige Integrationsvorlagen den Administratoren vor, etwa solche, die ein Widget in die CRM-Karte einbauen. Einen einfachen eingehenden oder ausgehenden Webhook kann ein Mitarbeiter selbst anlegen, und er arbeitet mit dessen Rechten. Einen eigenen Schalter „Webhooks nur für Administratoren" gibt es nicht. Ein Administrator sollte deshalb die Liste der Webhooks regelmäßig durchsehen (wo sie liegt, zeigt der nächste Abschnitt). Ein Verbot würde das Hauptrisiko ohnehin nicht lösen: Ein Webhook, den ein Mitarbeiter angelegt hat, sieht im CRM genau das, was dieser Mitarbeiter sieht.

Wo sehe ich vorhandene Webhooks, und wie lösche ich einen?

Öffnen Sie den Bereich für Entwickler und gehen Sie zur Liste der Integrationen. Ein Mitarbeiter sieht nur seine eigenen Webhooks, ein Administrator sieht alle und kann nach Autor filtern. Den Schlüssel (den geheimen Teil der URL) sieht nur sein Autor: Öffnet ein Administrator einen fremden Webhook, stehen dort Sternchen statt des Codes. Läuft eine Integration und niemand weiß mehr, wer sie gebaut hat, suchen Sie sie in dieser Liste nach Autor und Datum, nicht nach URL. Gelöscht wird ein Webhook über das Menü der Zeile in der Liste. Danach bekommt das externe System sofort Autorisierungsfehler, klären Sie also vorher, wer den Schlüssel nutzt. Webhooks ehemaliger Mitarbeiter prüfen Sie gesondert. Was mit ihnen beim Ausscheiden passiert, steht im Leitfaden zum Offboarding von Mitarbeitern.

Kann ich einen Webhook nur zum Lesen anlegen?

Ein Häkchen „nur lesen" gibt es beim eingehenden Webhook nicht. Die Rechte wählt man beim Anlegen pro Modul (CRM, Aufgaben, Benutzer usw.), und innerhalb eines Moduls kann der Webhook sowohl lesen als auch schreiben. Begrenzen lässt er sich nur über die Rechte des Benutzers, unter dem er läuft: Der Webhook stellt jede Anfrage im Namen seines Autors und ist an dessen Rolle gebunden. Daraus ergibt sich ein Weg, der funktioniert. Legen Sie einen eigenen Integrationsbenutzer an, geben Sie ihm eine CRM-Rolle mit reinem Lesezugriff auf die nötigen Elemente und erstellen Sie den Webhook unter diesem Benutzer. Gerät der Schlüssel in falsche Hände, kann damit nichts geändert oder gelöscht werden. Bedenken Sie, dass dieser Benutzer einen Platz im Benutzerlimit Ihres Tarifs belegt. Dafür hängt die Integration nicht mehr an einem bestimmten Manager: Verlässt er das Unternehmen, läuft der Datenaustausch weiter.

Was gebe ich einem Dienstleister, der uns Leads schicken soll?

Meist wird nach „einer URL oder einem Webhook" gefragt, und beides meint dasselbe: die Adresse eines eingehenden Webhooks, die sein System mit crm.lead.add aufruft. Geben Sie einen Schlüssel nur mit dem CRM-Modul heraus, angelegt unter dem Integrationsbenutzer aus dem vorigen Abschnitt und nicht unter Ihrem eigenen Administratorkonto. Die Adresse wirkt wie ein Passwort: Wer sie hat, kann in Ihr CRM schreiben. Endet die Zusammenarbeit mit dem Dienstleister, löschen Sie den Webhook in der Liste der Integrationen, und der Zugriff ist sofort weg. Muss der Dienstleister nur Anfragen von einer Website senden, ist ein CRM-Formular einfacher: Dann braucht es gar keinen Schlüssel für die REST-API.

Der Roboter «Ausgehender Webhook»: Was gehört in das Feld „Handler"?

In Bitrix24 gibt es den Standardroboter «Ausgehender Webhook». Er hat ein einziges Feld, „Handler", in das Sie die Adresse Ihres Dienstes eintragen: http oder https, mit Domainnamen. Der Roboter schickt dorthin eine Anfrage mit der Kennung des Dokuments (document_id, zum Beispiel beim Deal DEAL_10) und macht sofort weiter. Er wartet nicht auf eine Antwort und gibt nichts an den Prozess zurück. Die Felder des Deals schickt er auch nicht mit. Hängen Sie die benötigten Werte als Parameter an die Adresse an: https://example.com/hook?deal={=Document:ID}&sum={=Document:OPPORTUNITY}. Noch eine Eigenheit: Ist REST in Ihrem Tarif nicht verfügbar, tut der Roboter stillschweigend nichts, und im Protokoll erscheint kein Fehler. Brauchen Sie einen Autorisierungs-Header, einen JSON-Body oder die Antwort des Dienstes in einer Prozessvariablen, nehmen Sie „HTTP-Anfrage". Darf das Ereignis nicht verloren gehen, nehmen Sie „Ausfallsicherer Webhook": Er wiederholt den Versand nach Zeitplan, bis zu zehn Versuche.

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.