Skip to main content
Poku needs a public URL to forward inbound SMS and call summaries to your agent. How you set this up depends on where your agent is running.

​
Step 1: Get a public URL

​
Option A — Local machine (via ngrok)

If your agent is running on your local machine, use ngrok to create a public tunnel.
  1. Create an account at ngrok.com.
  2. After logging in, follow the installation instructions for your operating system. On macOS you can install via Homebrew: 
    brew install ngrok
  3. Grab your authtoken from the ngrok dashboard and authenticate: 
    ngrok config add-authtoken <your-token>
  4. Start a tunnel pointed at the port your agent is listening on: 
    ngrok http <your-agent-port>
    ngrok will output a forwarding URL: 
    Forwarding https://abc123.ngrok-free.app -> http://localhost:<your-agent-port>
    Copy this URL — you’ll need it in Step 3.

​
Option B — VPS (no ngrok needed)

If your agent is hosted on a VPS, it’s already on the public internet — no tunnel required. Recommended: Set up HTTPS using a reverse proxy such as nginx or Caddy with a free Let’s Encrypt certificate. This gives you a clean, secure URL: 
https://yourdomain.com
If you are not using a reverse proxy, open the port your agent is running on in your cloud provider’s security group or firewall dashboard. Your webhook URL will be: 
http://YOUR_VPS_IP:<your-agent-port>

​
Step 2: Configure your agent

Set up your agent to accept incoming POST requests at your chosen path. Refer to your agent’s documentation for how to handle incoming webhook payloads. The Poku payload includes the following fields:
FieldDescription
payload.fromPhone number the text or call was from
payload.bodyBody of the incoming text
payload.humanResponseSummary of the inbound call
Example: OpenClaw config Add a Poku mapping to the hooks section of ~/.openclaw/openclaw.json. For full details, see the OpenClaw webhook documentation. 
{
  "hooks": {
    "enabled": true,
    "token": "<openclaw-hooks-token>",
    "transformsDir": "~/.openclaw/hooks/transforms",
    "defaultSessionKey": "hook:ingress",
    "allowRequestSessionKey": false,
    "allowedSessionKeyPrefixes": [
      "hook:"
    ],
    "mappings": [
      {
        "match": {
          "path": "poku"
        },
        "action": "agent",
        "agentId": "main",
        "sessionKey": "hook:poku",
        "wakeMode": "now",
        "name": "Poku",
        "deliver": true,
        "channel": "telegram",
        "to": "<your-telegram-id>",
        "messageTemplate": "You received a message {{payload.payload.from}}: \"{{payload.payload.body}}\" {{payload.payload.humanResponse}}"
      }
    ]
  }
}

​
Step 3: Register your webhook with Poku

Register your public URL from Step 1 with Poku so inbound texts and calls get forwarded to your agent: 
curl -X POST "https://api.pokulabs.com/webhooks" \
  -H "Authorization: Bearer <your-poku-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"url":"<your-webhook-url>","eventTypes":["phone.sms.received","phone.call.received"]}'
If your agent requires an authorization header on incoming requests, include it via the optional headers field: 
curl -X POST "https://api.pokulabs.com/webhooks" \
  -H "Authorization: Bearer <your-poku-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"url":"<your-webhook-url>","eventTypes":["phone.sms.received","phone.call.received"],"headers":{"Authorization":"Bearer <your-agent-token>"}}'

​
Verify your webhook

You can check which webhook URL is currently registered on your account: 
curl -X GET https://api.pokulabs.com/webhooks \
  -H 'Authorization: Bearer <your-poku-api-key>'
This endpoint returns a list of registered webhooks.

​
Delete your webhook

You can delete any webhook URL registered on your account: 
curl -X DELETE "https://api.pokulabs.com/webhooks/<webhook-id>" \
  -H "Authorization: Bearer <your-poku-api-key>"