Principle:OpenHands OpenHands Payload Parsing

Knowledge Sources	OpenHands
Domains	Platform_Integration, Webhook_Processing
Last Updated	2026-02-11 21:00 GMT

Overview

Payload parsing is the design pattern of transforming raw, unstructured webhook payloads into strongly typed, polymorphic domain objects using the Factory pattern.

Description

Webhook payloads arrive as unstructured JSON dictionaries whose shape varies depending on the event type. A GitHub issue creation event has a different schema than a pull request review comment event, yet both must be processed by downstream logic that expects consistent interfaces. The payload parsing layer bridges this gap by:

1. Discriminating the event type from payload fields (e.g., examining the action field, the presence of pull_request vs. issue keys, or whether a comment is inline vs. top-level).
2. Constructing a typed domain object (a "view") that exposes a uniform interface while preserving the event-specific details.
3. Validating that required fields are present and well-formed, rejecting malformed payloads early in the pipeline.

This approach applies the Factory Method design pattern: a single factory function accepts the raw payload and returns one of several concrete types, all of which implement a common interface. Consumers downstream operate against the interface, not the concrete types, achieving polymorphic dispatch without conditional logic scattered throughout the codebase.

Usage

Apply this pattern when:

• Incoming data can represent multiple distinct event types with overlapping but non-identical schemas
• Downstream consumers need a uniform interface regardless of the specific event type
• The number of event types is expected to grow over time (new types can be added to the factory without modifying consumers)
• Type safety is desired to catch mismatched field access at development time rather than runtime

Theoretical Basis

1. Factory Method Pattern

The Factory Method pattern defines an interface for creating objects but lets subclasses or concrete implementations decide which class to instantiate. In the context of payload parsing:

create_view(payload) -> ViewInterface:
    event_type = discriminate(payload)
    match event_type:
        case ISSUE:         return IssueView(payload)
        case ISSUE_COMMENT: return IssueCommentView(payload)
        case PR_COMMENT:    return PRCommentView(payload)
        case INLINE_COMMENT: return InlinePRCommentView(payload)

The factory encapsulates the discrimination logic, keeping it in a single location.

2. Payload Discrimination

Discrimination is the process of determining which concrete type to instantiate from an untyped payload. The discriminator function inspects a set of distinguishing fields:

discriminate(payload):
    if "pull_request" in payload and "in_reply_to" in payload.comment:
        return INLINE_COMMENT
    if "pull_request" in payload:
        return PR_COMMENT
    if "issue" in payload and "comment" in payload:
        return ISSUE_COMMENT
    if "issue" in payload:
        return ISSUE

The order of checks matters: more specific types must be checked before more general ones to avoid misclassification.

3. Liskov Substitution Principle

All concrete view types produced by the factory must satisfy the Liskov Substitution Principle: any code that operates on the base ViewInterface must work correctly with any concrete implementation. This means all concrete types must implement the full interface contract, including properties like issue_number, repo_name, and installation_id.

4. Type Union as Sum Type

The set of concrete view types forms a sum type (also called a tagged union or discriminated union):

ViewType = IssueView | IssueCommentView | PRCommentView | InlinePRCommentView

This sum type enables exhaustive pattern matching in downstream code, ensuring all event types are handled.

Related Pages

Implemented By

• Implementation:OpenHands_OpenHands_GithubFactory_Create_View