Realtime Notifications

Get notified instantly when new help requests arrive — no polling needed.

Architecture

HeySummon uses Mercure for realtime event delivery via Server-Sent Events (SSE):

Consumer (AI agent)
  → POST /api/v1/help
    → HeySummon Platform stores request
      → Publishes event to Mercure Hub
        → Your SSE listener receives it instantly
          → Notification delivered to you

Mercure SSE (Recommended)

Subscribe to your provider topic for realtime push notifications:

curl -sN "http://localhost:3100/.well-known/mercure?topic=/hitlaas/providers/YOUR_USER_ID"

Events arrive as SSE data: lines containing JSON:

{
  "type": "new_request",
  "refCode": "HS-AB12",
  "question": "How do I fix deployment error X?"
}

Event Types

Type	Description
`new_request`	A new help request was submitted
`new_message`	A follow-up message in an existing conversation
`request_closed`	A conversation was closed

OpenClaw Integration

If you use OpenClaw, the recommended setup uses a persistent Mercure watcher that delivers events through OpenClaw’s messaging layer:

Setup

Mercure Watcher (pm2 background process) — maintains permanent SSE connection
OpenClaw /tools/invoke — channel-agnostic message delivery

The watcher script:

Listens on your Mercure provider topic via SSE
On new event: parses the data and calls OpenClaw’s /tools/invoke API
OpenClaw routes the message to your active channel (Telegram, WhatsApp, Discord, etc.)

# Example watcher output in your chat:
🦞 Nieuw HeySummon verzoek: HS-AB12
Type: new_request
Vraag: How do I fix deployment error X?

Why `/tools/invoke`?

The watcher doesn’t hardcode any messaging API. It calls OpenClaw’s gateway, which routes to whatever channel you’re using:

curl -s "http://127.0.0.1:18789/tools/invoke" \
  -H "Authorization: Bearer $OPENCLAW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "message",
    "args": { "action": "send", "message": "🦞 New request: HS-AB12" }
  }'

This means if you switch from Telegram to WhatsApp tomorrow, notifications keep working with zero config changes.

Watcher Script

See scripts/hitlaas-mercure-watcher.sh in the platform repository. Run it as a pm2 process:

pm2 start scripts/hitlaas-mercure-watcher.sh --name hitlaas-watcher --interpreter bash

Dashboard

The provider dashboard at /dashboard/requests also receives realtime updates via Mercure. New requests appear automatically without page refresh.

Self-Hosted Mercure

When self-hosting, Mercure runs as a Docker sidecar:

# docker-compose.yml
mercure:
  image: dunglas/mercure
  ports:
    - "3100:80"
  environment:
    MERCURE_PUBLISHER_JWT_KEY: "${MERCURE_JWT_SECRET}"
    MERCURE_SUBSCRIBER_JWT_KEY: "${MERCURE_JWT_SECRET}"

Set MERCURE_JWT_SECRET to match your platform’s MERCURE_JWT_SECRET environment variable.

OpenClaw Skill Overview