Laat je systeem over een stap beslissen

Laat een processtap je eigen systeem iets vragen en op het antwoord wachten: je ERP controleert een kredietlimiet, drukt een label af of keurt een retour goed. Picked roept je endpoint aan, het werk gaat slapen, en je systeem belt terug met de kant die het op moet.

Wanneer gebruik je dit

Gebruik dit recept als een beslissing hoort bij een systeem dat Picked niet zelf draait, en dat systeem in zijn eigen tempo kan antwoorden. Elke aanroep heeft een eigen terugbeladres, dus je systeem hoeft nooit uit te zoeken op welk stuk werk het antwoordt.

Hoeft je systeem alleen een signaal te sturen waar meerdere wachtende processen naar luisteren, hervat een proces dan met een signaal.

Bouw de stap

Open in de procesbouwer de stap die de vraag stelt:

1. Zet de invoer op Wachten.
2. Kies bij wat het wachten beëindigt voor Een antwoord van je eigen systeem.
3. Vul Je endpoint in: het https-adres dat Picked aanroept. Schrijf de host uit: die kan niet uit een variabele komen.
4. Optioneel: Headers, zoals een Authorization-header. Stuur een API-sleutel als {{ secret.name }} nadat je hem hebt toegevoegd onder Instellingen → Geheimen, nooit als gewone tekst. Headers gaan mee zoals ze er staan: alleen {{ secret.name }} wordt ingevuld, geen {{ variabelen }}.
5. Optioneel: Body, de velden die Picked meestuurt. Waarden kunnen {{ variabelen }} van het werk gebruiken, zoals {{ order_ref }}.
6. Opgeven na (minuten), tot een week (10080 minuten).
7. Teken vanaf de stap een uitgaande verbinding voor elke uitkomst die je systeem kan terugsturen, zoals approved en rejected, en één gewone verbinding voor al het andere. Ook timed_out en call_failed kunnen een eigen verbinding krijgen.

Publiceer het proces. Werk dat bij de stap aankomt, roept nu je endpoint aan en gaat daar slapen.

Een AI-agent die met Picked verbonden is kan dezelfde stap bouwen: vraag om een stap met een externe actie.

Wat je endpoint ontvangt

Een POST met je bodyvelden als JSON, en een picked-object ernaast:

POST /picked/check HTTP/1.1
Host: erp.example.com
Content-Type: application/json
Authorization: Bearer <your key>

{
  "order": "SO-48211",
  "picked": {
    "callback_url": "https://picked.nl/api/v1/process-runs/callbacks/q7Lx2VnR9bT4wE6yH1mK8sD3fG5jP0cZa1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6",
    "expires_at": "2026-10-14T09:30:00+00:00",
    "run_id": 5512,
    "step": "ask_erp"
  }
}

Beantwoord de aanroep zelf binnen 10 seconden met een 2xx, en doe het werk daarna. Een aanroep die te lang duurt, of 5xx, 408 of 429 antwoordt, wordt in totaal drie keer geprobeerd; elke andere 4xx niet opnieuw. Komt er geen enkele door, dan gaat de stap verder met de uitkomst call_failed.

Bel terug

Stuur een POST naar de callback_url, vóór expires_at. Er is geen API-token nodig: het adres is de sleutel, en het werkt alleen voor dit ene stuk werk. Bewaar het zoals je een wachtwoord bewaart.

• outcome (optioneel): welke verbinding het werk volgt, in kleine letters, cijfers en _. Zonder outcome is de uitkomst completed. Een uitkomst die geen verbinding noemt, volgt de gewone verbinding van de stap.
• data (optioneel): een willekeurig JSON-object, tot 100 sleutels op het hoogste niveau en 64 KB. Het werk kan het vanaf dan lezen als wait_payload, en de outputs van de stap halen hun velden eruit: zie hieronder.

curl -X POST "https://picked.nl/api/v1/process-runs/callbacks/q7Lx2VnR9bT4wE6yH1mK8sD3fG5jP0cZa1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "outcome": "approved",
    "data": { "credit_limit": 2500, "approved_by": "j.devries" }
  }'

HTTP/1.1 200 OK
Content-Type: application/json

{ "status": "woken" }

Gebruik het antwoord in latere stappen

Wil je een veld uit het antwoord in latere stappen tonen of gebruiken, en er niet alleen op vertakken, geef de stap er dan een output voor. Voeg in de builder onder Outputs van de stap er een per veld toe:

• Naam: hoe latere stappen het noemen, zoals suggested_bin. Geen naam die Picked zelf gebruikt, zoals order_id of wait_payload.
• Type: tekst, getal, waar/onwaar, object of lijst.
• Veld in het antwoord: waar het in data staat, met punten voor geneste velden, zoals bin of label.id.
• Standaard (optioneel): de waarde als het antwoord het veld weglaat, of als de stap is verlopen.

Latere stappen lezen het als {{ steps.<stap>.suggested_bin }}: in hun tekst, in actie-instellingen, in voorwaarden en in de body van een latere aanroep van je systeem.

Een callback waarvan data een veld zonder standaard mist, of er een van een ander type heeft, krijgt 422 met het veld erbij (data.bin), en het werk blijft wachten: stuur hem verbeterd opnieuw. JSON-typen tellen zoals ze verstuurd zijn: "4" is tekst, geen getal.

Lees het antwoord

Foutmeldingen noemt alle codes, en Rate limits wat je doet bij een 429.

Testen

Terugbellen kan niet als proefrun: een header Picked-Dry-Run: true antwoordt hier 400 en er gebeurt niets. Test met een eigen proces: laat de stap een endpoint aanroepen dat je zelf beheert, laat een stuk werk bij de stap aankomen, en roep de callback_url aan die je endpoint ontving.