Ihre Anwendung mit einer Automation verbinden

Senden Sie ein Anwendungsereignis, wenn in Ihrem System etwas passiert, z. B. eine Bestellung erstellt oder eine Zahlung empfangen wird. Ein Ereignis kann einen Lauf starten, einen wartenden Lauf fortsetzen oder einen Lauf mit einer passenden Abbruchregel abbrechen. Jede Automation hat eine einzige Ereignis-URL für alle drei Zwecke.

Automations is in Early access. Your workspace permissions determine which actions you can perform.

Falls Sie Automations nicht öffnen oder einen Entwurf erstellen können, lesen Sie Workspace-Zugriff und Bearbeitungsrechte.

Das Ereignis konfigurieren, das einen Lauf startet

Erstellen Sie eine Automation mit Event from your application als Trigger.
Legen Sie Event name fest, zum Beispiel order.created. Namen sind case-sensitive und dürfen Buchstaben, Ziffern, Punkte, Unterstriche oder Bindestriche enthalten.
Definieren Sie Event fields für die Daten, die Ihre Anwendung sendet. Für eine Bestellung fügen Sie ein String-Feld mit dem Namen order_id hinzu. Spätere Schritte können diese Felder verwenden.
Veröffentlichen Sie die Automation. Der Erfolgsbildschirm zeigt How to start a run mit der Ereignis-URL und einem Anfrage-Beispiel.

Um die Verbindungsdetails erneut zu finden, wählen Sie den Trigger aus und klicken Sie in der Schnellbearbeitung auf How to connect your application. Der erweiterte Editor zeigt die Verbindungsoptionen.

Entwurf simulieren oder die veröffentlichte Version ausführen

Verwenden Sie Preview workflow mit Beispieldaten, um Ihren Entwurf zu simulieren, ohne Nachrichten zu senden oder Daten zu ändern. Das Ausführen des cURL-Befehls, ein Klick auf Send event… oder die Nutzung von Start run führt die veröffentlichte Automation aus und kann reale Aktionen auslösen. Gespeicherte und ungespeicherte Entwurfsänderungen gelten nicht für diese Läufe.

Veröffentlichen Sie die Automation, bevor Sie Ereignisse senden. Wenn keine veröffentlichte Version existiert, wird die Anfrage sofort abgelehnt; das Ereignis wird nicht in die Warteschlange gestellt oder gespeichert. Editor-Beispiele können Entwurfsänderungen widerspiegeln – veröffentlichen Sie diese Änderungen, bevor Sie Daten senden, die darauf aufbauen.

Die URL kopieren und ein Ereignis senden

Verwenden Sie Copy request, um einen cURL-Befehl mit URL, Headern und Beispiel-Body zu erhalten. Ersetzen Sie die Beispielwerte durch die Daten Ihrer Anwendung.

Die URL enthält die Workspace- und Automations-IDs:

Codebeispiel

POST https://<your-regional-api-host>/v1/hooks/automations/<workspace-id>/<automation-id>

Verwenden Sie die vollständige URL aus dem Dashboard. Sie benötigen keinen X-Workspace-Id-Header. Die aktuelle Authentifizierungsoption ist No authentication: Jeder mit dieser URL kann Ereignisse senden. Bewahren Sie sie in Ihrer Serverkonfiguration auf.

Für eine Automation, die für order.created konfiguriert ist, setzen Sie AUTOMATION_EVENT_URL auf die kopierte URL und senden Sie:

Codebeispiel

curl --request POST "$AUTOMATION_EVENT_URL" \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "order.created",
    "data": { "order_id": "order_123" }
  }'

Setzen Sie type auf den konfigurierten Ereignisnamen und data auf ein Objekt, das den Event-Feldern entspricht. Optional können Sie occurred_at als RFC-3339-Zeitstempel angeben; der Standardwert ist der Zeitpunkt, an dem das Ereignis eintrifft.

Eine 202 Accepted-Antwort mit status: "queued" bestätigt, dass das Ereignis in die Warteschlange aufgenommen wurde. Bird erzeugt die Ereignis-ID und gibt sie als event_id zurück. Öffnen Sie den Tab Runs der Automation, um die Ausführung zu überprüfen. Die Aufnahme in die Warteschlange bestätigt nicht, dass das Ereignis einem Trigger entsprach oder ein Lauf gestartet wurde.

Sie können auch Send event… im Dashboard verwenden, um das Beispiel ohne Terminal abzusenden. Dies sendet ein echtes Ereignis.

Einen wartenden Lauf mit einem Ereignis fortsetzen

Ein Warteschritt verwendet dieselbe Automations-URL wie der Trigger. Sein Ereignisname und subject_key identifizieren, was passiert ist und welcher Lauf das Ereignis erhalten soll.

Aktivieren Sie in Automation settings die Optionen Skip overlapping runs und Use a business key. Setzen Sie Business key auf einen Wert, der die Bestellung, Rechnung oder ein anderes Objekt identifiziert. Für das Bestellbeispiel verwenden Sie den Ausdruck trigger.data.data.order_id.
Fügen Sie Wait for application event hinzu und konfigurieren Sie Ereignisname, Event-Felder und Timeout. Warten Sie zum Beispiel auf order.paid mit einem String-Feld payment_id.
Veröffentlichen Sie die Automation, senden Sie das startende Ereignis und warten Sie, bis der Lauf in Runs erscheint.
Senden Sie das Folgeereignis an dieselbe URL, mit subject_key gleich dem Business Key des Laufs:

Codebeispiel

{
  "type": "order.paid",
  "subject_key": "order_123",
  "data": { "payment_id": "payment_456" }
}

subject_key ist der Business-Key-Wert, z. B. order_123; es ist nicht die Ereignis-ID oder die Lauf-ID. Die erweiterte Verbindungsansicht des Warteschritts zeigt eine Anleitung für Ihren konfigurierten Key.

Ein passendes Ereignis kann nach dem Start des Laufs erfasst werden, auch bevor der Warteschritt erreicht wird. Ereignisse, die verarbeitet werden, bevor ein passender Lauf existiert, werden nicht für einen zukünftigen Lauf gespeichert. Ein Warteschritt mit Filter wird nur fortgesetzt, wenn sowohl die Event-Felder als auch der Filter übereinstimmen. Der Lauf nimmt den Timeout-Pfad, wenn kein passendes Ereignis vor Ablauf der Frist verarbeitet wird.

Abbruchregeln in Automation settings verwenden ebenfalls diese URL. Eine Regel kann alle aktiven Läufe der Automation oder den Lauf mit dem passenden subject_key betreffen. Konfigurieren Sie einen Filter, um einzuschränken, welche Läufe abgebrochen werden. Ein Abbruch kann eine bereits ausgeführte Aktion nicht rückgängig machen.

Veröffentlichte Versionen und pausierte Automationen

Neue Läufe verwenden die Version, die zum Zeitpunkt der Ereignisverarbeitung aktiv ist. Bestehende Läufe behalten ihre ursprüngliche Version, einschließlich ihrer Event-Felder und Wartebedingungen. Das Veröffentlichen eines geänderten Ereignisformats aktualisiert keine bereits gestarteten Läufe.

Das Pausieren einer veröffentlichten Automation stoppt neue Läufe. Ereignisse können bestehende Läufe weiterhin fortsetzen oder abbrechen, solange die Automation pausiert ist.

Zustellung und Wiederholungsversuche behandeln

Ereignisse werden asynchron verarbeitet und können wiederholt oder in geänderter Reihenfolge verarbeitet werden. Warten Sie, bis der startende Lauf existiert, bevor Sie ein Folgeereignis senden. Der occurred_at eines Ereignisses steuert nicht die Verarbeitungsreihenfolge, verlängert keinen Warteschritt und verhindert kein Timeout.

Der Wiederholungsschutz ist zeitlich begrenzt. Wenn Wiederholungseinträge ablaufen oder verloren gehen, kann ein Ereignis erneut verarbeitet werden, möglicherweise gegen eine neuere Version oder einen anderen aktiven Lauf. Entwerfen Sie Ihre Anwendung so, dass sie doppelte Ereignisse toleriert.

Um den Wiederholungsschutz zu nutzen, senden Sie beim ersten Versuch einen Idempotency-Key mit und verwenden Sie ihn bei Wiederholungen mit derselben URL und unverändertem Body erneut. Verwenden Sie für jede neue Anfrage einen neuen Key. Eine Wiederholung gibt denselben event_id zurück. Der Idempotenz-Leitfaden erläutert das begrenzte Wiedergabefenster und Konfliktantworten.

Ein Ereignis untersuchen

Die Anfrage gibt 4xx zurück: Prüfen Sie die Fehlerdetails der Antwort, die URL und die erforderlichen Felder type und das Objekt data. Senden Sie Content-Type: application/json. Der gesamte Anfrage-Body darf maximal 25 KB (25.000 Bytes) groß sein; größere Bodies geben 413 zurück.
Die Automation wurde nicht veröffentlicht: Veröffentlichen Sie sie, bevor Sie ein Ereignis senden. Das abgelehnte Ereignis wird nicht aufbewahrt; senden Sie nach dem Veröffentlichen eine neue Anfrage.
Die Anfrage gibt 202 zurück, aber kein Lauf startet: Prüfen Sie, ob die Automation aktiv ist, der Ereignisname dem Trigger entspricht und die Daten den veröffentlichten Event-Feldern entsprechen. Der Überlappungsschutz kann einen neuen Lauf überspringen, solange ein anderer aktiv ist. Prüfen Sie auch das monatliche Laufkontingent; am Limit übersprungene Starts werden nicht für den nächsten Monat in die Warteschlange gestellt.
Der Lauf verbleibt bei einem Warteschritt: Prüfen Sie Ereignisname, exakten Business Key, Datenfelder, Filter und Timeout. Verwenden Sie das Ereignisformat der ursprünglich veröffentlichten Version des Laufs.
Ein Wiederholungsversuch gibt einen Konflikt zurück: Wiederholen Sie die Anfrage mit dem ursprünglichen Key und unverändertem Request. Wenn Sie ein anderes Ereignis senden möchten, verwenden Sie einen neuen Key.

Die Hülle der Anfrage wird vor dem Einreihen in die Warteschlange geprüft. Event-Daten werden bei der Verarbeitung gegen Trigger, Warteschritte und Abbruchregeln geprüft. Ein in die Warteschlange aufgenommenes Ereignis kann daher keinem davon entsprechen.

Nächste Schritte

Automations öffnen, um Ihren Workflow zu konfigurieren und zu veröffentlichen.
Idempotente Wiederholungsversuche behandeln in Ihrer Anwendung.
Auf ein Ereignis warten in einem laufenden Workflow.
Die Automations-Leitfäden durchsuchen.

Verwandte Ressourcen