hermes - 💡(How to fix) Fix [Feature]: Add route-level webhook debounce/coalescing [1 comments, 2 participants]

Feature Description

Add route-level debounce/coalescing for webhook routes so bursts of related webhook POSTs can be collapsed into one agent run or one deliver_only notification.

This should be generic webhook infrastructure, not provider-specific behavior.

Motivation

Hermes already has webhook idempotency for exact duplicate delivery IDs, but many providers emit several distinct webhook deliveries for one logical event or conversation burst.

Examples:

• Chat/webhook integrations may emit one POST per message, but the user wants Hermes to wait briefly and process the latest message set together.
• GitHub/GitLab/Todoist-style sources can emit multiple updates while an object is converging to a final state.
• deliver_only notification routes can spam Telegram/Slack/etc. when several related events arrive within seconds.
• Agent routes can waste model calls and hit provider rate limits by processing transient intermediate states.

The key distinction: idempotency handles exact retries; debounce/coalescing handles related but distinct deliveries.

Proposed Solution

Add optional route config like:

platforms:
  webhook:
    extra:
      routes:
        waha-inbound:
          events: [message]
          debounce:
            key: "{payload.chatId}"
            wait_seconds: 90
            max_wait_seconds: 300
            strategy: batch_last
            batch_template: "- {payload.from}: {payload.body}"
          prompt: |
            Recent watched messages:
            {debounce.batch}
          deliver: telegram
          deliver_only: true

Suggested fields:

• key: template/dot-path expression used to group related deliveries, scoped by route.
• wait_seconds: quiet window before flushing.
• max_wait_seconds: maximum time to keep extending a burst.
• strategy:
  • last: keep only the latest payload.
  • first: keep the first payload.
  • batch: expose all buffered payloads.
  • batch_last: expose all buffered payloads and use latest payload as the primary template context.
• batch_template: optional per-item template for rendering {debounce.batch}.
• optional max_items / max_bytes safety caps.

Expected Behavior

• Works for both normal agent routes and deliver_only: true routes.
• Auth, body size limits, event filtering, and payload filters should still happen before buffering.
• Exact delivery-id idempotency remains separate and still prevents provider retry duplication.
• When a webhook is buffered, the HTTP response should succeed quickly, e.g. 202 {"status":"buffered","debounce_key":"..."}.
• When the quiet window expires, Hermes executes/delivers once with the selected/coalesced payload.
• Logs should show route, debounce key hash/safe value, buffered count, and chosen strategy.
• State should be profile-safe. A first version can be in-memory with documented limitations; a later durable queue can persist across gateway restarts.

Alternatives Considered

• External sidecars that implement debounce and then call Hermes once. Works today, but duplicates routing logic outside Hermes and makes common webhook use cases harder to configure.
• Relying on upstream webhook provider settings. Many providers do not expose debounce/coalescing controls.
• Idempotency only. Not enough because these are distinct webhook deliveries with different delivery IDs.

Related

• General payload filtering: https://github.com/NousResearch/hermes-agent/issues/10572
• Prior provider-specific coalescing request: https://github.com/NousResearch/hermes-agent/issues/13456