New — webhooks your AI agents can wait on. Hook & Sense opening to early access.
Request access →

basics

Getting Started

Wire up the MCP server, create a callback endpoint, and have your agent await a signed result with wait_for_callback in minutes.

HookSense is the webhook and callback layer for AI agents. An agent creates a callback endpoint, hands the URL to a long-running tool, a human approver, or another agent, then awaits the signed result over MCP with wait_for_callback instead of polling. This guide gets you from zero to a verified, replayable callback in minutes.

The Agent Flow (MCP)

The fastest path is through the MCP server. Point Claude Desktop, Cursor, or any MCP client at HookSense and your agent calls these tools:

  1. create_callback_endpoint — mint a fresh URL to hand to an external system
  2. wait_for_callback — block until the result arrives, signature-verified and decrypted (no polling loop)
  3. get_callback_payload / verify_signature — read the body and confirm it's authentic

Use it for long tool calls, human-in-the-loop approvals, multi-agent hand-offs, and external async jobs.

1. Create an Endpoint

From an agent, call create_callback_endpoint. Or go to hooksense.com and click Create Endpoint — you'll get a unique callback URL instantly, no signup required for the free tier.

https://hooksense.com/w/your-slug

Sign in (GitHub or email) to claim the endpoint, raise daily limits, and unlock features like custom slugs, signature verification, and team sharing.

2. Send a Test Request

Verify capture with a quick cURL before pointing a real provider or agent at it:

curl -X POST https://hooksense.com/w/YOUR_SLUG \
  -H "Content-Type: application/json" \
  -d '{"event": "test", "data": {"id": 123}}'

A waiting wait_for_callback resolves the instant the request lands; in the web UI it appears immediately via WebSocket.

3. Connect a Provider or External System

Any system that can POST to a URL works — payment providers, CI, or another service your agent kicked off. Common providers:

Stripe

  1. Go to Stripe Dashboard → Developers → Webhooks → Add endpoint
  2. Endpoint URL: https://hooksense.com/w/YOUR_SLUG
  3. Select events (e.g., checkout.session.completed, invoice.paid) and save
  4. Copy the signing secret (whsec_...) and paste it into the HookSense endpoint's signature config for automatic verification

GitHub

  1. Repo → Settings → Webhooks → Add webhook
  2. Payload URL: https://hooksense.com/w/YOUR_SLUG
  3. Content type: application/json
  4. Set a secret, paste it into HookSense signature config (provider: GitHub), and save

Shopify

  1. Admin → Settings → Notifications → Webhooks → Create webhook
  2. URL: https://hooksense.com/w/YOUR_SLUG, format JSON, latest API version
  3. Copy the secret from the Webhooks page footer and add it to HookSense signature config

4. Read the Callback

When the result arrives, your agent's wait_for_callback returns it; get_callback_payload exposes the full record, and the web UI shows the same:

  • HTTP method, status, source IP, latency
  • All request headers
  • Body with JSON formatting and syntax highlighting (decrypted at retrieval)
  • Query parameters and content type
  • Auto-detected provider (Stripe, GitHub, Shopify, Twilio, SendGrid, Paddle, Linear, Slack)
  • Signature verification badge (Verified / Invalid) when a secret is configured

5. Forward to Localhost (Optional)

Run your handler on your machine while the public URL stays stable:

npx hooksense listen -p 3000

Every captured webhook is also forwarded to http://localhost:3000. See CLI docs for path mapping, login, and troubleshooting.

What's Next

Next CLI