Bitrix24-Webhook feuert nicht: wo das Ereignis verloren geht

Ein Webhook, der „nicht funktioniert", sind in Bitrix24 (Alaio) zwei ganz verschiedene Fehler unter einem Wort, und keine der Lösungen hilft dem jeweils anderen: Entweder erreicht ein ausgehendes Ereignis Ihren Handler nie, oder ein eingehender Aufruf liefert einen Fehler statt Daten. Eine tote Synchronisation, ein Bot, der nicht mehr schreibt, ein Buchhaltungssystem ohne die Deals von gestern — jedes davon ist einer dieser beiden Fälle in Verkleidung. Bestimmen Sie zuerst, welcher es ist, und gehen Sie dann die Prüfungen der Reihe nach durch.

Ausgehend oder eingehend: welche Hälfte ist kaputt?

Ein eingehender Webhook ist eine URL mit Schlüssel, mit der Ihr Dienst das Portal aufruft; ein ausgehender ist das Gegenteil — das Portal ruft Sie, wenn ein Ereignis eintritt. Zeigen Ihre Logs eine ausgehende Anfrage und einen zurückkommenden Fehlerstring, liegt es am eingehenden, und der Fehler benennt die Ursache. Zeigen sie gar nichts, liegt es am ausgehenden — und nirgends existiert ein Fehler, was die Diagnose so zäh macht. Wie beide angelegt werden, steht im Webhook-Guide; hier geht es darum, was zu tun ist, wenn sie schweigen.

Warum erreicht ein ausgehender Webhook meinen Handler nie?

Ereignisse laufen nicht direkt vom Portal zu Ihrer URL. Sie werden auf einem separaten Zustellserver in eine Warteschlange gelegt, und erst dieser sendet den POST. Drei Eigenschaften dieses Servers erklären den größten Teil der Stille. Der Handler muss aus dem öffentlichen Internet erreichbar sein: Eine Adresse auf localhost oder in einem privaten Netz erhält nichts, und eine Firewall, die nur bekannte Partner durchlässt, wirkt genauso. Er muss schnell antworten: Die Warteschlange beobachtet die Antwortzeit und ruft langsame Handler seltener auf, mit wachsendem Abstand zwischen den Versuchen — ein schwerfälliger Handler wird unzuverlässig, ohne je sichtbar zu scheitern. Und die Nutzlast ist bewusst dünn, im Wesentlichen die Entitäts-ID und der Ereignisname, sodass Code, der fertige Feldwerte erwartet, eine leere Struktur liest. Die Felder holen Sie mit einem separaten REST-Aufruf.

Ist es wirklich das Ereignis, das ich abonniert habe?

Der zweithäufigste Grund ist ein intaktes Abonnement auf das falsche Ereignis. Update-Ereignisse feuern bei jeder Änderung der Entität, auch bei denen, die Ihre eigene Automatisierung vornimmt — das sieht nach doppelten Zustellungen aus und wird gelegentlich zur Schleife. Handler aus dem Bereich für Entwicklerressourcen und Handler, die eine Anwendung über event.bind registriert, liegen in verschiedenen Listen: Das Abonnement, auf das Sie schauen, muss nicht das laufende sein — und die Bindungen einer Anwendung verschwinden, wenn diese entfernt oder aktualisiert wird. Die Prüfung kostet eine Minute: Lösen Sie die Aktion von Hand aus und sehen Sie im Access-Log nach, ob ein POST ankommt.

Mein Handler war offline — bekomme ich das Ereignis zurück?

Nein, und genau diese Eigenschaft übersehen die meisten Integrationsentwürfe. Antwortet Ihr Server nicht oder liefert er einen Fehler, protokolliert der Warteschlangenserver den Fehlschlag und sendet das Ereignis nicht erneut. Es gibt keine Wiederholungen und keine Dead-Letter-Queue: Zehn Sekunden Deployment kosten lautlos jedes Ereignis dieses Zeitfensters.

Es gibt zwei Antworten. Für die eingehende Richtung binden Sie das Abonnement als Offline-Ereignis — das Portal hält die Ereignisse in einer Warteschlange, die Ihr Dienst im eigenen Tempo mit event.offline.get abholt; eine Ausfallzeit verzögert die Zustellung dann, statt sie zu vernichten. Für Aufrufe, die im Portal beginnen, senden Sie sie aus einem Workflow: Ausfallsicherer Webhook wiederholt fehlgeschlagene Versuche in einem von Ihnen gesetzten Intervall, lässt Sie festlegen, welche Statuscodes als Erfolg gelten, meldet die Zahl der Versuche und benachrichtigt ausgewählte Mitarbeiter, wenn die Zustellung endgültig scheitert.

Warum liefert ein eingehender Webhook einen Fehler?

Hier bekommen Sie einen Code — lesen Sie ihn, nicht den Satz daneben. Ein Scope-Fehler heißt, der Schlüssel wurde ohne die Berechtigung angelegt, die die Methode braucht, und Scopes sind bei der Erstellung fixiert: Der Schlüssel muss neu ausgestellt werden. Ein Zugriffsfehler heißt meist, der Schlüssel ist in Ordnung, sein Besitzer nicht: Ein Webhook handelt mit den Rechten des Mitarbeiters, der ihn angelegt hat — ein deaktivierter Besitzer oder einer, der die Pipeline nicht sieht, scheitert mit völlig gültigem Token. QUERY_LIMIT_EXCEEDED ist die Ratenbegrenzung und kein kaputter Schlüssel: Massenoperationen gehören in Batch-Aufrufe, mit Wiederholung und wachsender Verzögerung. Ein Aufruf über einfaches HTTP statt HTTPS wird sofort abgelehnt.

Wie teste ich einen Webhook, statt zu raten?

Protokollieren Sie den rohen Anfragekörper vor dem Parsen: Die Hälfte aller „Webhook kaputt"-Fälle ist ein Handler, der den POST bekommen hat und am eigenen Parsing gescheitert ist. Prüfen Sie auch den Absender — mit Ereignisaufrufen kommt ein Anwendungstoken, und der Abgleich mit dem gespeicherten Wert ist zugleich Sicherheitsprüfung und schnelle Antwort auf die Frage, ob dieser POST überhaupt aus dem Portal kam.

Die Gegenrichtung testen Sie aus dem Portal heraus: Setzen Sie HTTP-Anfrage GET/POST in einen Workflow — sie schickt eine Anfrage an Ihren Endpunkt und liefert Antworttext, Statuscode und ein Y/N-Kennzeichen zurück, zeigt also, ob Ihr Endpunkt dem Netz des Portals überhaupt antwortet; Wert aus JSON per Pfad extrahieren holt ein Feld für eine lesbare Logzeile heraus. Startete der Workflow, der die Anfrage senden sollte, gar nicht erst, führt die Spur zu Automatisierungsregeln, die nicht laufen.

Wie geht es weiter

Stille bedeutet ausgehend, ein Fehlerstring bedeutet eingehend: Allein diese Trennung spart den größten Teil der Zeit. Danach planen Sie mit der Einschränkung statt gegen sie — Ereignisse werden nie erneut gesendet, also läuft alles, was nicht verloren gehen darf, eingehend über ein Offline-Abonnement und ausgehend über den ausfallsicheren Webhook, beides gewöhnliche Bausteine der Automatisierungsregeln in Bitrix24. Die übrigen stehen im Roboteka-Katalog; fehlt der passende, beschreiben Sie die Aufgabe — wir bauen ihn kostenlos für die gemeinsame Bibliothek.