Skip to main content

​
What are webhook tools?

PromptWall can call your APIs to get verified data before answering. You register endpoints in the tool registry, and PromptWall decides when to call them based on the user’s prompt.

​
Register a tool

curl -X POST https://api.prompt-wall.com/v1/tools/registry \
  -H "Authorization: Bearer pk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "billing_api",
    "description": "Internal billing + revenue metrics",
    "webhook_url": "https://api.acme.com/v1/billing",
    "auth_type": "bearer",
    "auth_token": "internal_token_here",
    "grounding_keywords": ["revenue", "mrr", "arr", "billing"],
    "trust_tier": "verified",
    "timeout_ms": 3000,
    "rate_limit_rpm": 120
  }'
Response: 
{
  "id": "tool_abc123",
  "name": "billing_api",
  "signing_secret": "whs_xxxxxxxxxxxxx"
}

​
Verify HMAC signatures

PromptWall signs every call to your webhook with HMAC-SHA256 using the signing_secret it returned. Your webhook must verify: 
import hmac, hashlib

def verify_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)
The signature is sent in X-PromptWall-Signature header.

​
Security

  • Webhooks MUST respond within timeout_ms (default 5s)
  • Must return 2xx for success
  • SSRF protection blocks private IPs and non-HTTPS URLs
  • Rate-limited per-tool based on rate_limit_rpm
  • Credentials encrypted with customer-specific KMS key

​
Test your tool

curl -X POST https://api.prompt-wall.com/v1/tools/registry/{tool_id}/test \
  -H "Authorization: Bearer pk_..."
Returns: 
{"ok": true, "status_code": 200, "latency_ms": 142}