Skip to content

API Reference

Public imports from github_webhook_types.

github_webhook_types

Typed GitHub webhook payload helpers.

GitHubEventName = Literal['branch_protection_configuration', 'branch_protection_rule', 'check_run', 'check_suite', 'code_scanning_alert', 'commit_comment', 'create', 'custom-property-values', 'custom_property', 'delete', 'dependabot_alert', 'deploy_key', 'deployment', 'deployment_protection_rule', 'deployment_review', 'deployment_status', 'discussion', 'discussion_comment', 'fork', 'github_app_authorization', 'gollum', 'installation', 'installation_repositories', 'installation_target', 'issue-dependencies', 'issue_comment', 'issues', 'label', 'marketplace_purchase', 'member', 'membership', 'merge_group', 'meta', 'milestone', 'org_block', 'organization', 'package', 'page_build', 'personal_access_token_request', 'ping', 'project', 'project_card', 'project_column', 'projects_v2', 'projects_v2_item', 'projects_v2_status_update', 'public', 'pull_request', 'pull_request_review', 'pull_request_review_comment', 'pull_request_review_thread', 'push', 'registry_package', 'release', 'repository', 'repository_advisory', 'repository_dispatch', 'repository_import', 'repository_ruleset', 'repository_vulnerability_alert', 'secret_scanning_alert', 'secret_scanning_alert_location', 'secret_scanning_scan', 'security_advisory', 'security_and_analysis', 'sponsorship', 'star', 'status', 'sub-issues', 'team', 'team_add', 'watch', 'workflow_dispatch', 'workflow_job', 'workflow_run']

WebhookPayload = dict[str, Any]

WebhookPayloadModel = BaseModel

DeliveryHeaders

Bases: TypedDict

Relevant GitHub webhook delivery headers normalized to Python keys.

Source code in src/github_webhook_types/_headers.py 
 8
 9
10
11
12
13
14
class DeliveryHeaders(TypedDict, total=False):
    """Relevant GitHub webhook delivery headers normalized to Python keys."""

    event: Required[str]
    delivery: Required[str]
    signature_256: NotRequired[str]
    hook_id: NotRequired[str]

UnknownWebhookActionError

Bases: ValueError

Raised when no generated model is available for a GitHub webhook action.

Source code in src/github_webhook_types/_errors.py 
10
11
class UnknownWebhookActionError(ValueError):
    """Raised when no generated model is available for a GitHub webhook action."""

UnknownWebhookEventError

Bases: ValueError

Raised when no generated model is available for a GitHub webhook event.

Source code in src/github_webhook_types/_errors.py 
6
7
class UnknownWebhookEventError(ValueError):
    """Raised when no generated model is available for a GitHub webhook event."""

parse_delivery(event: str, payload: bytes | str | Mapping[str, object]) -> WebhookPayloadModel

Validate a GitHub webhook delivery payload for the given event name.

Source code in src/github_webhook_types/_parse.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
def parse_delivery(event: str, payload: bytes | str | Mapping[str, object]) -> "WebhookPayloadModel":
    """Validate a GitHub webhook delivery payload for the given event name."""
    payload_data = _coerce_payload(payload)
    action = payload_data.get("action")
    model_type = None

    if isinstance(action, str):
        model_type = EVENT_MODEL_BY_NAME_AND_ACTION.get((event, action))
        if model_type is None and event in EVENT_ACTIONS_BY_NAME and event not in EVENT_MODEL_BY_NAME:
            msg = f"No generated GitHub webhook model is registered for event {event!r} with action {action!r}."
            raise UnknownWebhookActionError(msg)

    if model_type is None:
        model_type = EVENT_MODEL_BY_NAME.get(event)

    if model_type is None:
        if event in EVENT_ACTIONS_BY_NAME:
            msg = f"No generated GitHub webhook model is registered for event {event!r} without a supported action."
            raise UnknownWebhookActionError(msg)
        msg = f"No generated GitHub webhook model is registered for event {event!r}."
        raise UnknownWebhookEventError(msg)

    return model_type.model_validate(payload_data)