HOKIO / DEVELOPER GUIDES
Receive AI provider callbacks on localhost with n8n
Disclosure: this article is written by the team behind Hokio, a webhook relay for local applications. The n8n workflow pattern below is provider-agnostic and works with any tunnel that gives you a public HTTPS URL. Where our product is the subject, we say so and state its limits.
The awkward middle of an async AI job
Some AI work does not fit inside one HTTP request. A document summarisation over a long file, an image generation queue, a transcription batch, an agent job that takes minutes: you submit the work, the provider acknowledges the submission, and the result exists some time later.
Providers handle "later" in one of two ways. You poll — ask every few seconds whether the job finished, which wastes requests and adds latency. Or, where the provider supports it, you pass a callback URL at submission time and the provider POSTs the completed result to it.
The callback approach has an uncomfortable assumption baked in: the callback URL must be publicly reachable. If your orchestration runs in local n8n — on your workstation or a homelab box — your machine has no public address. The usual workarounds are all bad in some way:
- Deploy first, develop later. Push the workflow to a cloud host just so the provider can reach it. Now your iteration loop includes deployments, and your credentials live somewhere else.
- Ephemeral tunnels. A free tunnel URL works for one afternoon of testing, but the URL rotates on restart. Callback URLs you already submitted to providers point at dead addresses — and unlike a dashboard webhook you can reconfigure, an in-flight job's callback target is already recorded on the provider's side.
- Skip callbacks, poll instead. Fine for low volume; wasteful and slow at anything else, and some providers charge per request.
What the pattern actually needs is a callback address that stays the same across restarts and reboots, so a job submitted now can find your machine tomorrow morning.
How the pattern fits together
When your provider supports asynchronous jobs with callback URLs, the flow is:
Your app → AI provider: submit job + callback URL
AI provider → Hokio HTTPS URL → local n8n Webhook
n8n → validate event → find job → update local state
Two honest caveats before the setup. First, this is a provider-dependent pattern, not a built-in capability of every AI API — check your provider's documentation for callback/webhook support and for how it handles delivery failures. Second, a webhook URL does not give an AI tool unrestricted access to your machine: the callback endpoint should be one workflow path, authenticated, and nothing more.
1. Prepare the local n8n webhook workflow
Start from a working local n8n with a public webhook base URL — that setup (Docker Compose bound to loopback, N8N_WEBHOOK_URL, path-restricted public surface) is covered in the n8n local webhook guide; complete it first.
Then build the callback receiver:
- Add a Webhook trigger:
POST, Pathai-job-completed. - Restrict the relay/tunnel to the exact test and production paths for this workflow (
/webhook-test/ai-job-completedand/webhook/ai-job-completed). - Start with an immediate response and harmless event inspection before adding side effects.
- Add an If node after the trigger. Check
{{ $json.body.status }}equalscompleted, and route unmatched events to a separate branch for failed or pending jobs. Also require a nonemptyevent_idandjob_idbefore any business action.
2. Test with a synthetic callback — no provider, no API charges
Save this as event.json. The field names are illustrative; map your provider's actual schema:
{
"event_id": "evt-demo-001",
"job_id": "job-demo-001",
"event": "job.completed",
"status": "completed",
"result": {"summary": "Demo result; no customer data"}
}
Enable the test listener and send (Windows PowerShell: use curl.exe):
curl -i -X POST https://YOUR_ASSIGNED_HOKIO_HOST/webhook-test/ai-job-completed -H "Content-Type: application/json" --data-binary @event.json
Confirm the If node selects the completed branch. Repeat with "status":"failed" and verify the alternate branch routes correctly. This test never calls an AI provider and incurs no API charges — which is exactly how you want to debug the routing logic, not with real jobs.
3. Connect the actual provider
When the synthetic loop works, wire up the real thing:
- Authenticate the Webhook node. The sender must support the authentication method you configure. An open callback path on the public internet will be found and probed.
- Implement the provider's signature verification if available. Verify the signature against the raw payload bytes before changing or parsing signed payloads — most signature schemes break the moment a middleware re-serialises the JSON.
- Store the provider job ID when you submit the job, so the incoming callback can be matched to the correct local record. Without that mapping, a callback is an orphan: valid, signed, and useless.
- Publish the workflow and give the provider the production callback URL:
https://YOUR_ASSIGNED_HOKIO_HOST/webhook/ai-job-completed
4. Dedup and idempotency: the part people skip
Callback delivery over the public internet is at-least-once in practice. Providers retry on timeouts, network blips duplicate deliveries, and your own re-tests generate repeats. If "update the local record and notify the user" runs twice, you have double-charged a customer, sent two emails, or generated two images.
The discipline, in the terms we ship in the guide:
- Persist each verified event ID in a database with a unique constraint before doing any business action.
- Claim the event atomically and skip duplicates. An insert that fails on the unique constraint means someone already processed it.
- A simple If node alone does not prevent races. Two near-simultaneous deliveries both pass the If check; only the database constraint catches the second one. n8n's flow logic is not a concurrency primitive — your storage is.
- Use the provider's retry policy and reconcile job status after outages. If your machine was offline when a callback fired, the provider may have given up. Reconciling job state (polling the provider's job-status endpoint for anything that never called back) is the safety net.
- Keep processing short, or hand work off after a durable receipt. A successful HTTP response proves the callback was received; it does not prove a later local action succeeded. If the workflow does heavy work inline and crashes mid-way, the provider saw a 200 and will not retry.
This is also where the relay's honesty matters: Hokio does not queue events while your device is offline. The URL stays assigned, the sender gets an immediate failure, and the provider's retry policy — not ours — is what gives you a second chance. If your use case cannot tolerate a missed callback during downtime, you need reconciliation logic regardless of which tool you use.
The permanence argument, stated plainly
For AI callbacks specifically, URL stability matters more than for ordinary webhooks. A dashboard webhook can be reconfigured after the URL changes; a job submitted to a provider three hours ago carries the callback URL it was given at submission. If that address rotated when your tunnel restarted, the result has nowhere to land.
Hokio assigns each endpoint a permanent HTTPS URL under *.hooks.hokio.top. The connector opens a single outbound WebSocket to the relay — no port forwarding, no inbound firewall holes — and the address survives agent restarts, reboots, and moves between relay nodes. Per-link policy restricts the public surface to exactly the methods and paths you allow, so the callback endpoint is reachable and the rest of the machine is not.
What to build next
- Document summarisation: receive the completion event and update a local job record.
- Image generation: receive the result reference, then validate its origin before downloading anything.
- Human review: prepare a draft from the callback payload and require approval before publishing.
The local half of every step above runs without a Hokio account. The full walkthrough lives at hokio.dev/guides/n8n-ai-callbacks, with guides for Express, FastAPI, and a dependency-free Python receiver alongside it. Access is invitation-based during pre-launch. Eligible trials require a payment method at secure checkout and billing starts after the displayed trial end unless cancelled first.
Official reference: n8n Webhook node configuration. Provider authentication and retry behaviour must follow your provider's own documentation.
Keep building.
Browse all webhook integration guides →
Installation and connection help in the webhook quick start →