Je applicatie verbinden met een automatisering

Stuur een applicatie-event wanneer er iets gebeurt in je systeem, zoals het aanmaken van een bestelling of het binnenkomen van een betaling. Een event kan een run starten, een run vervolgen die erop wacht, of een run annuleren met een overeenkomende annuleringsregel. Elke automatisering heeft één event-URL voor alle drie de toepassingen.

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

Als je Automations niet kunt openen of geen concept kunt maken, zie toegang tot de werkruimte en bewerkingsrechten.

Configureer het event dat een run start

Maak een automation met Event from your application als trigger.
Stel Event name in, bijvoorbeeld order.created. Namen zijn hoofdlettergevoelig en mogen letters, cijfers, punten, underscores of koppeltekens bevatten.
Definieer Event fields voor de data die je applicatie verstuurt. Voeg voor een bestelling een stringveld toe met de naam order_id. Latere stappen kunnen deze velden gebruiken.
Publiceer de automation. Het successcherm toont How to start a run, inclusief de event-URL en een voorbeeldverzoek.

Om de verbindingsgegevens later terug te vinden, selecteer je de trigger en klik je op How to connect your application in de snelle bewerking. De uitgebreide editor toont de verbindingsopties.

Simuleer een concept of voer de gepubliceerde versie uit

Gebruik Preview workflow met voorbeelddata om je concept te simuleren zonder berichten te versturen of data te wijzigen. Het uitvoeren van het cURL-commando, klikken op Send event… of gebruiken van Start run voert de gepubliceerde automation uit en kan echte acties uitvoeren. Opgeslagen en niet-opgeslagen conceptwijzigingen zijn niet van toepassing op die runs.

Publiceer de automation voordat je events verstuurt. Als er geen gepubliceerde versie is, wordt het verzoek direct geweigerd; het event wordt niet in de wachtrij geplaatst of bewaard voor later. Editorvoorbeelden kunnen conceptwijzigingen weerspiegelen, dus publiceer die wijzigingen voordat je data verstuurt die ervan afhankelijk is.

Kopieer de URL en verstuur een event

Gebruik Copy request om een cURL-commando te krijgen met de URL, headers en een voorbeeldbody. Vervang de voorbeeldwaarden door de data van je applicatie.

De URL bevat de werkruimte- en automation-ID's:

Codevoorbeeld

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

Gebruik de volledige URL die je uit het dashboard hebt gekopieerd. Je hebt geen X-Workspace-Id-header nodig. De huidige authenticatieoptie is No authentication: iedereen met deze URL kan events versturen. Bewaar de URL in je serverconfiguratie.

Stel voor een automation die geconfigureerd is voor order.created AUTOMATION_EVENT_URL in op de gekopieerde URL en verstuur:

Codevoorbeeld

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

Stel type in op de geconfigureerde eventnaam en data op een object dat overeenkomt met de eventvelden. Je kunt ook occurred_at meegeven als RFC 3339-tijdstempel; standaard wordt het tijdstip gebruikt waarop het event binnenkomt.

Een 202 Accepted-respons met status: "queued" bevestigt dat het event in de wachtrij staat. Bird genereert de event-identifier en retourneert deze als event_id. Open het tabblad Runs van de automation om de uitvoering te inspecteren. Acceptatie door de wachtrij bevestigt niet dat het event een trigger heeft geactiveerd of dat er een run is gestart.

Je kunt ook Send event… in het dashboard gebruiken om het voorbeeld te versturen zonder terminal. Dit verstuurt een echt event.

Ga verder met een run die wacht op een event

Een wachtstap gebruikt dezelfde automation-URL als de trigger. De eventnaam en subject_key identificeren wat er is gebeurd en welke run het moet ontvangen.

Schakel in Automation settings Skip overlapping runs en Use a business key in. Stel Business key in op een waarde die de bestelling, factuur of een ander object identificeert. Gebruik voor het bestelvoorbeeld de expressie trigger.data.data.order_id.
Voeg Wait for application event toe en configureer de eventnaam, eventvelden en timeout. Wacht bijvoorbeeld op order.paid met een string payment_id-veld.
Publiceer, verstuur het startende event en wacht tot de run verschijnt in Runs.
Verstuur het vervolgevent naar dezelfde URL, met subject_key gelijk aan de business key van de run:

Codevoorbeeld

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

subject_key is de business-key-waarde, zoals order_123; het is niet de event-ID of de run-ID. De uitgevouwen verbindingsweergave van de wachtstap toont richtlijnen voor je geconfigureerde key.

Een overeenkomend event kan worden vastgelegd nadat de run is gestart, zelfs voordat deze de wachtstap bereikt. Events die worden verwerkt voordat een overeenkomende run bestaat, worden niet bewaard voor een toekomstige run. Een wachtstap met een filter gaat alleen verder als zowel de eventvelden als het filter overeenkomen. De run volgt het timeoutpad als er geen geschikt event wordt verwerkt vóór de deadline.

Annuleringsregels in Automation settings gebruiken ook deze URL. Een regel kan alle actieve runs van de automation targeten, of de run die overeenkomt met subject_key. Configureer een filter om te beperken welke runs worden geannuleerd. Een annulering kan een actie die al heeft plaatsgevonden niet ongedaan maken.

Gepubliceerde versies en gepauzeerde automations

Nieuwe runs gebruiken de versie die actief is wanneer het event wordt verwerkt. Bestaande runs behouden hun originele versie, inclusief hun eventvelden en wachtcondities. Het publiceren van een gewijzigd eventformaat werkt runs die al zijn gestart niet bij.

Het pauzeren van een gepubliceerde automation stopt nieuwe runs. Events kunnen bestaande runs nog steeds voortzetten of annuleren terwijl de automation gepauzeerd is.

Verwerk bezorging en retries

Events worden asynchroon verwerkt en kunnen opnieuw worden geprobeerd of in een andere volgorde worden verwerkt. Wacht tot de startende run bestaat voordat je een vervolgevent verstuurt. De occurred_at van een event bepaalt niet de verwerkingsvolgorde, verlengt geen wachttijd en voorkomt geen timeout.

Retrybescherming is begrensd. Als retryrecords verlopen of verloren gaan, kan een event opnieuw worden verwerkt, mogelijk tegen een nieuwere versie of een andere actieve run. Ontwerp je applicatie zodat deze dubbele events kan verwerken.

Om bescherming tegen herhaalde verwerking in te schakelen, stuur je bij de eerste poging een Idempotency-Key mee en hergebruik je die met dezelfde URL en ongewijzigde body bij nieuwe pogingen. Gebruik een nieuwe key voor elk nieuw verzoek. Een herhaald verzoek retourneert dezelfde event_id. De idempotentiegids legt het begrensde herhalingsvenster en conflictantwoorden uit.

Los een eventprobleem op

Het verzoek retourneert 4xx: Controleer de foutdetails in de respons, de URL en de vereiste type- en object data-velden. Verstuur Content-Type: application/json. De volledige requestbody mag maximaal 25 KB (25.000 bytes) groot zijn; grotere body's retourneren 413.
De automation is niet gepubliceerd: Publiceer deze voordat je een event verstuurt. Het geweigerde event wordt niet bewaard; verstuur een nieuw verzoek na het publiceren.
Het verzoek retourneert 202, maar er start geen run: Controleer of de automatisering actief is, of de eventnaam overeenkomt met de trigger en of de data overeenkomt met de gepubliceerde eventvelden. Overlapbeveiliging kan een nieuwe run overslaan zolang een andere actief is. Controleer ook de maandelijkse runlimiet; starts die bij de limiet worden overgeslagen, worden niet in de wachtrij gezet voor de volgende maand.
De run blijft staan bij een wachtstap: Controleer de eventnaam, de exacte business key, datavelden, het filter en de timeout. Gebruik het eventformaat van de oorspronkelijke gepubliceerde versie van de run.
Een retry retourneert een conflict: Probeer opnieuw met de oorspronkelijke sleutel en een ongewijzigd verzoek. Als je een ander event wilt versturen, gebruik dan een nieuwe sleutel.

Het foutantwoord van het verzoek wordt gecontroleerd vóór het in de wachtrij plaatsen. Eventdata wordt tijdens de verwerking gecontroleerd tegen de trigger, wachtstap en annuleringsregels, dus een event in de wachtrij kan met geen van deze overeenkomen.

Volgende stappen

Open Automations om je workflow te configureren en publiceren.
Verwerk idempotente retries in je applicatie.
Wacht op een event in een lopende workflow.
Bekijk de Automations-gidsen.

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

ImplementatiegidsPreview your first automation