888                        888
                                                      888                        888
                                                      888                        888
.d8888b  888  888  888  8888b.  888d888 88888b.d88b.  88888b.   .d88b.   .d88b.  888  888
88K      888  888  888     "88b 888P"   888 "888 "88b 888 "88b d88""88b d88""88b 888 .88P
"Y8888b. 888  888  888 .d888888 888     888  888  888 888  888 888  888 888  888 888888K
     X88 Y88b 888 d88P 888  888 888     888  888  888 888  888 Y88..88P Y88..88P 888 "88b
 88888P'  "Y8888888P"  "Y888888 888     888  888  888 888  888  "Y88P"   "Y88P"  888  888

        Zero-cost webhook infrastructure for AI agents

  ╔════════════════════════════════════════════════════════════════╗
  ║     Ephemeral Webhook Inboxes for Autonomous Agents            ║
  ║     No servers. No costs. Just webhooks that work.             ║
  ╚════════════════════════════════════════════════════════════════╝

  💡 WHAT IS SWARMHOOK?
  ────────────────────────
  SwarmHook gives AI agents instant webhook URLs without servers, config, or costs.

  🤖 If you are an AI agent, read the <a href="/skill.md">skill.md</a> file for full documentation!

  Perfect for:
  • Receiving marketplace notifications (SwarmMarket, eBay, etc.)
  • Monitoring payment events (Stripe, PayPal, crypto)
  • Tracking GitHub webhooks, CI/CD pipelines
  • Any async event your agent needs to respond to

  🎯 THE PROBLEM:
  ────────────────
  Your AI agent needs webhooks, but you don't want to:
  ✗ Spin up a server just to receive HTTP POSTs
  ✗ Configure nginx, SSL certs, and DNS
  ✗ Pay $5-20/month for a VPS
  ✗ Deal with ngrok tunnels that expire

  ✓ THE SOLUTION:
  ────────────────
  1. Create an ephemeral inbox (takes 2 seconds)
  2. Get a public webhook URL: https://swarmhook.com/in/inbox_abc123
  3. Register that URL with any service (SwarmMarket, Stripe, GitHub, etc.)
  4. Poll for events or stream them in real-time
  5. Inbox auto-deletes after 24-48 hours

  No servers. No config. Just works.

  💡 HOW IT WORKS:
  ────────────────
  1. You create an ephemeral inbox (24-48hr lifetime)
  2. You get a public webhook URL: https://swarmhook.com/in/inbox_abc123
  3. Register that URL with external services (SwarmMarket, Stripe, etc.)
  4. Poll for events or stream them in real-time
  5. Inbox auto-deletes when expired

  🚀 QUICK START:
  ────────────────
  # 1. Register as an agent
  curl -X POST https://swarmhook.com/api/v1/agents/register \
    -H "Content-Type: application/json" \
    -d '{"name": "MyAgent"}'
  # Returns: {"agent_id": "...", "api_key": "swh_..."}

  # 2. Create webhook inbox
  curl -X POST https://swarmhook.com/api/v1/inboxes \
    -H "X-API-Key: swh_your_key"
  # Returns: {"inbox_id": "inbox_abc123", "webhook_url": "https://swarmhook.com/in/inbox_abc123"}

  # 3. Poll for events
  curl https://swarmhook.com/api/v1/inboxes/inbox_abc123/events \
    -H "X-API-Key: swh_your_key"

  Done! Now register that webhook_url with any service.

  🔒 SECURITY:
  ────────────────
  ✓ API keys required for agent & inbox management
  ✓ Webhook URLs are unguessable (cryptographic random IDs)
  ✓ Rate limiting on all endpoints
  ✓ Request validation & sanitization
  ✓ No PII stored (just webhook payloads)
  ✓ Auto-expiring inboxes (ephemeral by design)

  💰 PRICING:
  ────────────────
  Free Tier:
  • 5 concurrent inboxes
  • 100 events per inbox
  • 48 hour max TTL
  • 60 requests/minute

  Premium (Coming Soon):
  • Unlimited inboxes
  • 10,000 events per inbox
  • 7 day TTL
  • Priority support

  📖 SKILL FILES (for AI agents):
  ├── <a href="/skill.md">/skill.md</a>        Full documentation & usage guide
  └── <a href="/skill.json">/skill.json</a>      Machine-readable metadata

  🔗 API ENDPOINTS:
  ├── <a href="/health">/health</a>               Health check
  │
  ├── /api/v1/agents        Agent management
  │   ├── POST /register         Register new agent
  │   └── GET  /me               Your profile & stats
  │
  ├── <a href="/api/v1/inboxes">/api/v1/inboxes</a>       Inbox management
  │   ├── POST /                 Create inbox (requires agent key)
  │   ├── GET  /{id}             Inbox details (requires inbox key)
  │   └── GET  /{id}/events      Poll events (supports long polling)
  │       ?wait=60               Long poll (wait up to 60s)
  │       ?unread=true           Only unread events
  │       ?mark_read=true        Mark as read
  │       ?since=ISO8601         Events since timestamp
  │       ?limit=50              Max events to return
  │
  ├── /api/v1/inboxes       Event streaming
  │   └── GET  /{id}/stream      Server-Sent Events stream
  │
  └── /in/{inbox_id}        Webhook receiver (public)
      ├── POST /                 Receive webhook from any source
      └── GET  /                 Check inbox status

  📚 DOCUMENTATION:
  ────────────────
  • Quick Start:   https://github.com/digi604/swarmhook#readme
  • Security:      https://github.com/digi604/swarmhook/blob/main/SECURITY.md
  • Deploy Guide:  https://github.com/digi604/swarmhook/blob/main/DEPLOYMENT.md

  Built with ❤️  for the autonomous agent economy
  From the builders of swarmmarket.io