Place‑Busyness-Webhooks sind eine kostenpflichtige Erweiterung. Wende dich an deine MotionTools-Ansprechperson, um sie aktivieren zu lassen. Wenn du nicht weißt, was Place‑Busyness-Webhooks sind, erfährst du hier mehr darüber.
Überblick
Webhook-Subscription einrichten
Admin-User können Webhook-Subscriptions in der MotionTools-Dashboard anlegen.
Geh zu Einstellungen → Webhooks und klicke auf Neuen Webhook anlegen.
Aktiviere den Webhook.
Gib dem Webhook einen Namen und trage die Endpoint-URL ein, an die du Webhooks empfangen möchtest.
Setze anschließend den customer_id-Filter: Klicke auf Regel hinzufügen und gib customer_id als Feldnamen sowie die ID des Kunden als Wert ein, dessen Orte du überwachen möchtest.
Der customer_id-Filter ist erforderlich. Du kannst keine Busyness-Webhook-Subscription ohne ihn erstellen. So wird sichergestellt, dass Webhooks nur für die relevanten Orte gesendet werden.
Scrolle nach unten und aktiviere das Event busyness.place_changed in der Webhook‑Gruppe Busyness Signals.
Scrolle bis zum Ende der Seite und klicke auf Speichern.
Webhook-Subscription testen
Nachdem du eine Subscription erstellt hast, solltest du einmal end-to-end prüfen, dass dein Endpoint einen korrekten Webhook empfängt, bevor du es in deine Produktionssysteme integrierst.
Da Busyness-Webhooks durch reale Nachfrage im Betrieb in einem wiederkehrenden Rhythmus ausgelöst werden (und nicht über einen Button „on demand“), braucht ein Test eine bewusste Vorbereitung. Diese Anleitung zeigt dir, wie du selbst eine echte Busyness-Änderung erzeugst und die Zustellung überprüfst, ohne Unterstützung durch MotionTools.
Die wichtigste Regel: Erstelle den Ort und die erste Buchung bevor du die Webhook-Subscription erstellst. Geeignete Orte werden gecacht; ein Ort, der nach dem Erstellen der Subscription angelegt oder geändert wird, kann sonst erst nach bis zu ein paar Stunden berücksichtigt werden. Wenn du die Reihenfolge unten einhältst, vermeidest du das.
Bevor du startest
Die Busyness-Erweiterung ist aktiviert (falls du unsicher bist: wende dich an deine MotionTools-Ansprechperson).
Du hast Admin-Zugriff auf die MotionTools-Dashboard.
Du hast ein Fahrer-Konto und Zugriff auf die Fahrer App, um Test-Touren zu disponieren.
Du hast einen Endpoint, der Webhooks empfangen kann. Für einen schnellen Test eignet sich ein kostenloser Inspection-Endpoint wie webhook.site: öffne ihn und kopiere die einzigartige URL. Realistischer ist ein Staging-Endpoint in deinem eigenen System.
Schritt 1: Einen geeigneten Ort vorbereiten
Ein Ort erhält nur Webhooks, wenn er aktiv (nicht archiviert), kürzlich aktiv (mindestens eine Buchung in den letzten 7 Tagen) ist und zum Kunde gehört, den du im Filter verwendest. Richte das zuerst ein:
Erstelle (oder wähle) einen Kunde in der Dashboard und notiere dir dessen
customer_id. Du brauchst sie für die Subscription.Erstelle einen Ort für diesen Kunde und setze dabei gleichzeitig seine
external_id.Erstelle eine Buchung, die diesen Ort als Abholort nutzt.
Disponiere und beende eine Tour für diese Buchung: gehe als Fahrer online, disponiere die Buchung in eine Tour und starte und beende sie. So wird der Ort als „kürzlich aktiv“ registriert.
Setze die external_id, wenn der Ort zum ersten Mal im Rahmen der Buchung erstellt wird. Wenn ein Ort später neu erstellt oder „geforkt“ wird (z. B. weil MotionTools den alten Ort archiviert und bei einer Namensänderung einen neuen erstellt), kann die externe Referenz brechen und external_id als null ankommen. Am zuverlässigsten ist es, den Ort gemeinsam mit der Buchung zu erstellen, damit die external_id von Anfang an am Ort hängt.
Nach dieser ersten Aktivität kann es etwas dauern (bis zu ein paar Stunden), bis der Ort als geeigneter, gecachter Ort erkannt wird, bevor du weitermachst.
Schritt 2: Webhook-Subscription erstellen
Erstelle jetzt die Subscription wie oben unter Webhook-Subscription einrichten beschrieben:
Endpoint URL: die Receiver-URL für den Test, wie oben beschrieben
customer_id-Filter: der Kunde aus Schritt 1.
Beim ersten Durchlauf kommt kein Webhook. Beim ersten Auswertungszyklus speichert MotionTools den aktuellen Busyness-Wert als Baseline. Dein erstes Webhook wird im nächsten Zyklus gesendet, in dem sich der gerundete Busyness-Wert tatsächlich ändert. Ein stiller erster Zyklus ist erwartbar und kein Fehler.
Schritt 3: Eine Busyness-Änderung auslösen
Busyness ist das Backlog-Verhältnis: offene Touren im Verhältnis zur aktiven Fahrer-Kapazität im Geschäftsgebiet. Um den Wert über eine 10er-Stufe zu bewegen, erhöhst du die Nachfrage, während du die Fahrer-Kapazität niedrig hältst:
Dupliziere die Buchung aus Schritt 1 und disponiere sie zwei Mal oder öfter, um mehr offene Touren aufzubauen.
Halte wenige oder keine Fahrer online. Wenn kein (oder nur ein) Fahrer online ist, während die Nachfrage steigt, geht das Backlog Verhältnis über
0.Prüfe, ob sich das Backlog Verhältnis in der Analytics Split View bewegt hat. Denk daran: Ein Webhook wird nur gesendet, wenn der Wert in eine neue 10er-Stufe wechselt (z. B.
0→10), nicht bei jeder Änderung innerhalb derselben Stufe.
Schritt 4: Auf den nächsten Auswertungszyklus warten
Busyness wird nach dem konfigurierten Zeitplan neu berechnet; standardmäßig alle 10 Minuten (Minimum 5). Warte mindestens einen vollständigen Zyklus, nachdem du die Änderung ausgelöst hast.
Schritt 5: Zustellung verifizieren
Prüfe deinen Receiver. Du solltest pro geeignetem Ort genau eine busyness.place_changed-Zustellung sehen, mit:
place_idundservice_area_id, die zu deinem Test-Ort und dessen Geschäftsgebiet passencustomer_id, passend zu deinem Subscription-Filterexternal_id, passend zu dem Wert aus Schritt 1 (nichtnull)busyness, auf die nächste 10er-Stufe abgerundeteinem
changed_at-Timestamp
Wenn der Ort zu mehr als einem Geschäftsgebiet gehört, erwarte ein Webhook pro Gebiet, dessen Stufe sich geändert hat.
Troubleshooting
Symptom | Wahrscheinliche Ursache & Lösung |
Es kommt gar kein Webhook an | Der Ort ist möglicherweise nicht geeignet. Prüfe, ob er aktiv (nicht archiviert) ist, in den letzten 7 Tagen eine Buchung hatte und zum |
Kein Webhook, aber alles wirkt geeignet | Wenn du den Ort oder die Buchung nach der Subscription erstellt hast, kann das Eligibility-Caching die Aufnahme um bis zu ein paar Stunden verzögern. Erstelle Ort und Buchung zuerst neu, dann die Subscription (siehe Hinweis oben). |
| Der Ort wurde vermutlich neu erstellt oder geforkt, nachdem die |
Backlog-Ratio hat sich bewegt, aber es kommt kein Webhook | Erwartbar, wenn der Wert innerhalb derselben 10er-Stufe blieb oder wenn dies der erste (Baseline-)Durchlauf der Subscription war. |
Backlog-Ratio bleibt bei | Es gibt nicht genug offene Nachfrage im Verhältnis zu den online verfügbaren Drivers. Dispatche mehr Buchungen und/oder reduziere die Anzahl der online verfügbaren Drivers. |