POST /webhook/inbound/{webhook_name}

Receive Webhook Payload

Receive an inbound webhook payload and forward it to the PocketPaw agent for processing. Validates the webhook secret, parses the payload, and publishes it to the message bus.

Overview

Receives an external webhook payload and forwards it to the agent as an inbound message. Supports both async (fire-and-forget) and synchronous (wait for agent response) modes.

Authentication is via webhook secret header, not the standard Bearer token.

Parameters

Path Parameters

webhook_name required
string

The webhook slot name to receive the payload on.

Query Parameters

wait
boolean = false

If true, waits for the agent to process the payload and returns the response synchronously.

Header Parameters

X-Webhook-Secret
string

Webhook verification secret (must match the slot’s secret).

X-Webhook-Signature
string

Alternative: HMAC-SHA256 signature of the request body using the slot’s secret.

Response (Async)

status string
"accepted"
request_id string
Unique ID for tracking the webhook delivery

Response (Sync — ?wait=true)

status string
"ok"
response string
The agent’s response to the webhook payload
Terminal window
curl -X POST "http://localhost:8000/webhook/inbound/github-events" \
  -H "X-Webhook-Secret: whsec_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{"action": "opened", "issue": {"title": "Bug report"}}'
const response = await fetch(
  "http://localhost:8000/webhook/inbound/github-events",
  {
    method: "POST",
    headers: {
      "X-Webhook-Secret": "whsec_a1b2c3d4e5f6...",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      action: "opened",
      issue: { title: "Bug report" }
    })
  }
);
const data = await response.json();
console.log(data);
import requests


response = requests.post(
    "http://localhost:8000/webhook/inbound/github-events",
    headers={"X-Webhook-Secret": "whsec_a1b2c3d4e5f6..."},
    json={
        "action": "opened",
        "issue": {"title": "Bug report"}
    }
)
print(response.json())
{
  "status": "accepted",
  "request_id": "wh_abc123"
}
Request
curl -X POST "http://localhost:8000/webhook/inbound/{webhook_name}" \
  -H "Content-Type: application/json"
const response = await fetch("http://localhost:8000/webhook/inbound/{webhook_name}", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
},
});

const data = await response.json();
console.log(data);
import requests

response = requests.post(
    "http://localhost:8000/webhook/inbound/{webhook_name}",
    headers={'Content-Type':'application/json'},
)

print(response.json())
package main

import (
    "fmt"
    "net/http"
    "io"
)

func main() {
    req, _ := http.NewRequest("POST", "http://localhost:8000/webhook/inbound/{webhook_name}", nil)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
Response
Send a request to see the response