Your first webhook.
From the web to localhost.

1. Run a local webhook receiver

You need Python 3.11 or newer for this example. Download webhook_receiver.py into an empty directory, review the file, and run it:

python webhook_receiver.py

On Windows, use py -3 webhook_receiver.py if your Python installation uses the py launcher. On Linux, use python3 webhook_receiver.py.

Expected startup message: Listening on http://127.0.0.1:8000/webhook. Leave this terminal open. The receiver binds to loopback; it does not open a listener on your public network interface.

2. Test the receiver locally

In a second terminal, send a sample event. In Windows PowerShell, use curl.exe instead of curl for these commands.

Create event.json in the same directory with this content:

{"event":"task.completed","source":"local-demo"}

Then send the request:

curl -i -X POST http://127.0.0.1:8000/webhook -H "Content-Type: application/json" --data-binary @event.json

Expected result: HTTP 200 and:

{"received":true,"event":"task.completed"}

If the local request fails, fix that before starting the tunnel. Hokio forwards to your application; it does not start that application for you.

3. Install and connect Hokio

Windows

Get Hokio from the Microsoft Store ↗. Use the device connection instructions shown by your Hokio workspace. Select local application port 8000 to match the receiver.

Linux

The installer detects your architecture and Linux environment and verifies the selected release checksum:

curl -fsSL https://hokio.dev/download/install.sh | sh

With an active workspace, ask your workspace owner for a one-time device connection code, or generate one from Connect a device if your role allows it. Then run:

hokio-agent login --panel-url https://hokio.dev --port 8000 --connect

Enter the code when prompted; avoid putting it in a shared command or screenshot. The connector displays your assigned webhook_url and keeps the foreground connection running. Codes expire and can be redeemed only once.

Your assigned URL comes from Hokio. Do not copy an illustrative hostname from a screenshot. Keep the receiver and connector running during the test.

Reconnect later

hokio-agent connect
hokio-agent status

Your assigned webhook address remains the same while the endpoint stays assigned. If you change the application port, update the connector to use the actual listening port:

hokio-agent config --port 8000

4. Send an event to your public HTTPS URL

Replace YOUR_ASSIGNED_HOKIO_HOST below with the hostname returned by your connector. The placeholder is not a working endpoint. Keep the /webhook path:

curl -i -X POST https://YOUR_ASSIGNED_HOKIO_HOST/webhook -H "Content-Type: application/json" --data-binary @event.json

A successful connection returns the same HTTP 200 receipt as the localhost test. You can also send this request from a second machine to verify that the URL is publicly reachable. Use synthetic event data for the test.

Paste the full URL, including /webhook, into the service that sends your AI callbacks or automation events. Configure the endpoint's allowed methods, accepted paths, source IP rules, and limits to fit that service.

Troubleshooting

Local connection refused

Check that the Python receiver is running on the same machine as the connector and on port 8000. If the port is occupied, choose a free port in the receiver and use that same port in Hokio.

The public URL returns unavailable

Check hokio-agent status, the internet connection, and whether the connector and local application are running. The URL stays assigned while offline, but requests are not queued for later delivery.

The request is denied

Ask your workspace owner to check source IP restrictions, HTTP methods, accepted paths, and traffic limits. Keep the policy restricted to the intended sender.

The code is rejected

Request a fresh one-time connection code from your workspace owner. An expired or already redeemed code cannot register another device.

Can I connect without an account?

No. Reading these guides and running the local receiver does not create a Hokio account or reserve a URL.