Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pokulabs.com/llms.txt

Use this file to discover all available pages before exploring further.

Poku needs a public URL to forward inbound events 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. Poku sends a JSON body for each event. All events share the same wrapper: 
{
  "eventType": "<event-type>",
  "payload": { ... }
}

​
message.received

Fired when an inbound SMS, WhatsApp, or Slack message is received on your number or workspace. 
{
  "eventType": "message.received",
  "payload": {
    "interactionId": "ia_abc123",
    "medium": "sms",
    "from": "+14155550199",
    "to": "+14155550100",
    "body": "Hey, are you available tomorrow?",
    "mediaUrls": []
  }
}
FieldTypeDescription
payload.interactionIdstring?Present when the message is a reply to a Poku interaction
payload.mediumstringChannel the message arrived on: sms, whatsapp, or slack
payload.fromstringSender’s phone number or Slack ID
payload.tostringYour Poku number or Slack channel that received the message
payload.bodystringText content of the message
payload.mediaUrlsstring[]?Media attachments, if any (MMS)

​
form.received

Fired when a recipient submits a form sent via SMS or WhatsApp. 
{
  "eventType": "form.received",
  "payload": {
    "interactionId": "ia_abc123",
    "values": {
      "email": "johnsmith@gmail.com",
      "phone": "+14155550199"
    }
  }
}
FieldTypeDescription
payload.interactionIdstringID of the interaction the form belongs to
payload.valuesobjectKey-value map of the submitted form fields

​
call.conversation.ended

Fired when an outbound call completes. 
{
  "eventType": "call.conversation.ended",
  "payload": {
    "interactionId": "ia_abc123",
    "summary": "Caller confirmed their appointment for tomorrow at 3pm.",
    "from": "+14155550199",
    "to": "+14155550100"
  }
}
FieldTypeDescription
payload.interactionIdstringID of the call interaction
payload.summarystringAI-generated summary of the conversation
payload.fromstringPhone number that placed the call
payload.tostringPhone number that received the call
Using OpenClaw? See the OpenClaw installation guide for the openclaw.json webhook config.

​
Step 3: Register your webhook with Poku

Register your public URL from Step 1 with Poku so events get forwarded to your agent. Specify which event types you want to receive: 
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": ["message.received", "form.received", "call.conversation.ended"]
  }'
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": ["message.received", "form.received", "call.conversation.ended"],
    "headers": {"Authorization": "Bearer <your-agent-token>"}
  }'
See the Create Webhook API reference for all available parameters.

​
Verify your webhook

You can check which webhooks are currently registered on your account: 
curl -X GET https://api.pokulabs.com/webhooks \
  -H 'Authorization: Bearer <your-poku-api-key>'
See the List Webhooks API reference for the full response schema.

​
Delete your webhook

curl -X DELETE "https://api.pokulabs.com/webhooks/<webhook-id>" \
  -H "Authorization: Bearer <your-poku-api-key>"
See the Delete Webhook API reference for details.