hokio.

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:

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:

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:

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:

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

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 →

Create your account →