Principle:OpenHands OpenHands Webhook Acknowledgment
| Knowledge Sources | |
|---|---|
| Domains | Platform_Integration, Webhook_Processing |
| Last Updated | 2026-02-11 21:00 GMT |
Overview
Webhook acknowledgment is the user experience pattern of providing immediate visual feedback to the event originator confirming that their request has been received and queued for asynchronous processing.
Description
When a user triggers an automated workflow through a webhook event (e.g., mentioning a bot in a GitHub comment), there is an inherent latency gap between the moment the event is received and the moment visible results appear. During this gap, the user has no way of knowing whether the system received their request, is processing it, or failed silently. Webhook acknowledgment bridges this gap by immediately posting a lightweight, visible signal back to the originating platform.
Common acknowledgment mechanisms include:
- Emoji reactions -- Adding an "eyes" or "rocket" emoji to the comment or issue that triggered the event
- Status checks -- Creating a pending commit status on a pull request
- Ephemeral messages -- Posting a transient message visible only to the triggering user (in chat platforms)
The acknowledgment must be:
- Immediate -- Sent before any long-running processing begins
- Lightweight -- Must not require the same resources as the full processing pipeline
- Idempotent -- Adding the same reaction twice should not produce duplicate visual artifacts
Usage
Apply this pattern whenever:
- The processing pipeline takes more than a few seconds to produce visible results
- The user needs confirmation that their request was received (not lost or filtered)
- The platform supports lightweight feedback mechanisms (reactions, status checks)
- Multiple users may be watching the same resource and need to see that automation is active
Theoretical Basis
1. Responsiveness in Asynchronous Systems
In human-computer interaction theory, perceived responsiveness is a key factor in user satisfaction. The Nielsen Norman Group identifies three response-time thresholds:
- 0.1 seconds: Feels instantaneous
- 1.0 second: Noticeable delay but flow is maintained
- 10 seconds: User's attention is lost
Since webhook-triggered agent execution can take minutes, the acknowledgment pattern ensures the 1-second threshold is met for the initial response, even though the full result takes much longer.
2. Token-Based Authentication for Platform APIs
To post acknowledgments, the system must authenticate to the platform's API. For GitHub Apps, this involves a two-step token acquisition:
get_installation_token(app_id, private_key, installation_id):
jwt = sign_jwt(app_id, private_key, expiry=10min)
token = exchange_jwt_for_installation_token(jwt, installation_id)
return token # valid for 1 hour
The installation token is scoped to the specific repository installation and grants the permissions configured for the GitHub App (e.g., writing reactions, posting comments).
3. Feedback Loop Model
The acknowledgment is the first step in a three-phase feedback loop:
Phase 1: Acknowledgment (immediate, <1s) -- "I received your request" Phase 2: Progress updates (periodic, seconds) -- "I am working on it" Phase 3: Final result (completion, minutes) -- "Here is the outcome"
Each phase reduces user uncertainty and builds trust in the automation system.
4. Idempotency of Reactions
Platform-specific reaction APIs typically enforce idempotency at the API level (adding the same reaction from the same actor twice is a no-op). However, the acknowledgment layer should still guard against duplicate acknowledgments in case the upstream deduplication fails:
acknowledge(event_id, resource):
if already_acknowledged(event_id):
return
add_reaction(resource, "eyes")
mark_acknowledged(event_id)