Auxot
Tutorials Docs Pricing Login

Trigger a workflow with an intake webhook

POST JSON from GitHub Actions, your backend, or a cron job — get a work_id back on the spot, poll until the workflow finishes, and wire the same pattern anywhere HTTP leaves off.

Plus: three pasted Admin-Agent briefs — create the intake + curl skeleton, decode a stuck poll from JSON, pick polling vs callback before you ship.

Audience Admins · Developers
Time ~10 min
Prerequisites A runnable workflow ([Run a workflow](/tutorials/run-a-workflow)) with at least two steps so async behavior is visible. An API key that can call Auxot’s HTTP API — personal keys work ([Generate your first API key](/tutorials/generate-your-first-api-key)); for automation the whole team relies on, create a Team API key on **Business or Enterprise** ([Create a shared Team API Key](/tutorials/create-a-team-api-key)). Permission to create intakes (typically org admin / workflow owner — **Settings → Intakes** or the workflow’s Intakes panel).
You'll end up with One intake URL wired to that workflow — plus a copy-paste POST, a poll loop against `work_id`, and a clear sense of when callbacks beat sleeping in your own cron.

When a tutorial shows italic text in quotation marks, it usually mirrors a label or helper string inside Auxot. Product copy changes between releases — if something reads differently in your workspace, trust what you see on screen.

Callouts with a Worth knowing gold accent are meant as must-read context before you move on. Blockquotes that open with Tip are lighter, optional depth.

Why this matters

Workflows are most useful when something outside Auxot kicks off the work: a signup form, a CI job, or a nightly reconciliation script. Intakes are the entry point: your service sends one authenticated POST, Auxot answers 202 Accepted immediately with a work_id, and the workflow runs on its own clock.

You’re not opening the Workflows page to click New task for every event. You still designed the workflow, created the intake, and stored the API key; the HTTP call is the trigger you wired, and everything else is the workflow you already designed.

That split matters in production: callers need a correlation handle (work_id) and a status check (poll or callback) because 202 only means queued, not done.

Quick start

  1. Open Intakes: Settings → Intakes → Add Intake or your workflow’s detail page → Intakes. Pick the workflow, name it, save. (Business and Enterprise: assign the right team before saving.)
  2. Copy three things: the intake id from the detail view, your Auxot base URL (same host you use in the browser, with https), and an API key (user.… or team.…).
  3. POST once: POST /v1/intake/{INTAKE_ID} with Authorization: Bearer … and a JSON body (any shape your workflow expects).
  4. Read work_id: response is 202 with {"work_id":"…"}.
  5. Poll until settled: GET /v1/intake/{INTAKE_ID}/work/{WORK_ID} with the same Bearer token until status reads completed or failed.

Done? Your external script can open a run and know when it finished, without pretending 202 meant success.

The agent can do that?

Paste planning prompts before you paste secrets into CI; Admin Agent can’t click Add Intake for you, but you can steal wording faster than rereading curl flags alone.

1. Create the intake + curl skeleton in one ask

Chat → Admin Agent:

Create an intake attached to my workflow named "[workflow name]" (or tell me if you need the exact slug). Then give me copy-paste curl for:
1) POST JSON {"source":"smoke-test","note":"from tutorial 62"} to trigger it
2) GET poll for work status
Use placeholders BASE_URL, INTAKE_ID, API_KEY, WORK_ID and remind me keys start with user. or team.

Why it’s non-obvious: Headers and paths vary across environments; one consolidated skeleton cuts typos. You still swap real IDs from Settings → Intakes after the intake exists.

2. Decode a stuck poll

When status lingers in pending / running, paste the latest poll JSON:

My intake poll shows this work item JSON: [paste]. We're over SLA — what's the first thing I should check in Auxot UI vs my caller?

Why it’s non-obvious: Bottlenecks split cleanly between provider capacity, human steps, and bad handoffs (Run a workflow); narration narrows where to click before you blame HTTP.

3. Callback vs poll: decide before load

We're wiring Intakes from [GitHub Actions / Lambda / internal queue]. Compare polling work_id vs configuring Auxot's callback URL on the intake — ops burden, retries, and secret handling for each.

Why it’s non-obvious: Poll loops are simple until hundreds fire per minute; callbacks shift reliability onto your receiver endpoint. Pick consciously: still your URLs and secrets in Settings → Intakes.

Go deeper

Auth headers

Intakes accept Bearer tokens only:

Team keys keep CI alive after individuals rotate; prefer them wherever Business / Enterprise allows.

Statuses

Poll responses include pending, running, completed, or failed; treat anything except completed and failed as still in progress. Back off politely (sleep + jitter) instead of hammering sub-second.

Example curl (replace placeholders)

Trigger:

curl -X POST "https://BASE_URL/v1/intake/INTAKE_ID" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticket_id":"SUP-1042","customer":"Acme Corp"}'

Poll (swap WORK_ID from the 202 body):

curl "https://BASE_URL/v1/intake/INTAKE_ID/work/WORK_ID" \
  -H "Authorization: Bearer API_KEY"

Use your real hostname: the docs use https://ai.yourcompany.com as an illustration (Intake Webhooks).

Troubleshooting

  • 401 Unauthorized: wrong key, revoked key, or header typo (Bearer + single space). Confirm Business/Enterprise team alignment when using team. keys.
  • 404 on POST: intake deactivated on purpose; callers shouldn’t be able to fingerprint whether it ever existed.
  • Instant failed: open the workflow task / audit trail (View your audit logs): usually malformed input vs step expectations, not HTTP.
Callbacks instead of polling

Set a default callback URL on the intake when you want Auxot to POST the finished work item to your service. Configure under Settings → Intakes or ask the Admin Agent with the URL you own. See Intake Webhooks → Callback URL.

Walkthrough

Step 1: Confirm the workflow runs manually

In Workflows, open your board, click New task, walk one happy path. Fix agents (Create an agent from scratch) before HTTP hides failures behind retries.

Step 2: Create the intake

Path A: Settings → Intakes → Add Intake → choose workflow → save.
Path B: workflow detail → Intakes → add (tooltip language matches webhook URLs external services can call).

Copy the INTAKE_ID from the detail screen.

Step 3: Pick the API key

Solo script → personal key. Shared automation → Team API Key (Create a shared Team API Key) so nobody’s offboarding deletes production.

Step 4: POST from your terminal

Replace BASE_URL, INTAKE_ID, API_KEY.

Verify HTTP/2 202 (or HTTP 1.1 equivalent) and JSON {"work_id":"…"}.
The job hasn’t run yet; that’s expected. 202 means the workflow is queued.

Step 5: Poll until terminal state

Loop GET …/work/{work_id} until completed or failed. Log failures with the returned payload: your workflow steps determine what “output” means.

Step 6 (optional): Callback URL

If your platform can’t poll, configure callback URL on the intake and implement an HTTPS receiver that validates Auxot’s POST.

Step 7: Lock down operational hygiene

  • Store keys in secret managers: never commit curl history with tokens.
  • Deactivate intakes when migrations pause traffic (404 shield).
  • Point teammates at View your audit logs and Trace a failing job end to end when forensics beat staring at poll JSON alone.

What’s next

Reference

Browse all tutorials