Skip to main content

Typed interactions with Github Webhooks

Project description

PyPI - Python Version PyPI - Status PyPI - License


Octohook makes working with incoming Github Webhooks extremely easy.

It parses the incoming payload into Python classes to allow for auto-complete and other goodies. For example, octohook provides functions for payload values which require string interpolation.

For example, almost every repository payload has an archive_url with some required and conditional parameters.

  "repository" : {
    "archive_url": "{archive_format}{/ref}"

The Repository model provides an archive_url() method which has archive_format as an argument and ref as an optional variable.

>>> repo.archive_url("hello")
>>> repo.archive_url("hello","world")"


Github doesn't send consistent payloads for each model. Depending on the event type, you can get more information for a particular model, or less. For example, Github sends a changes key with some payloads with the edited action. For other actions, the key is not present. In such cases, our event.changes is None.

This can happen for arbitrary payloads, so I'd suggest tailoring your code to the expected incoming webhook.

If anyone has a good suggestion on how to tackle this issue, feel free to email me, or create a PR!

Because Github sends different payloads for a combination of event type and action, unless I have access to all the variations, I cannot be sure that the corresponding model is correct.

Current coverage is documented here. If you can provide any of the missing events, please make a PR.

Sample Usage

from flask import Flask, request, Response
import octohook
from import PullRequestEvent
from octohook.models import PullRequest, Repository

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    github_event = request.headers.get('X-GitHub-Event') # pull_request

    # Assuming the incoming event was a PullRequestEvent
    event : PullRequestEvent = octohook.parse(github_event, request.json)

    return Response(, status=200)

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for octohook, version 0.3
Filename, size File type Python version Upload date Hashes
Filename, size octohook-0.3-py3-none-any.whl (11.6 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size octohook-0.3.tar.gz (11.5 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page