# Python GitHub Webhooks Framework
**NOTE:** Forked from [github_webhooks](https://github.com/karech/github-webhooks) as I needed to access more things:
- query params from incoming webhooks for identification
- `background_tasks` to handle long running webhook actions.
Simple and lightweight micro framework for quick integration with [GitHub
webhooks][1].
It's based on [FastAPI][3] and [pydantic][4], nothing more!
Async and mypy friendly.
[](https://github.com/morriz/github-webhooks/actions/workflows/ci.yml)
[][2]
## Installation
Just add `github-webhooks-framework2` package.
Example:
- `pip install github-webhooks-framework2`
- `poetry add github-webhooks-framework2`
## Example
Create file `example.py` and copy next code:
```python
import uvicorn
from pydantic import BaseModel
from github_webhooks import create_app
from github_webhooks.schemas import WebhookCommonPayload
# WebhookCommonPayload is based on pydantic.BaseModel
class PullRequestPayload(WebhookCommonPayload):
class Pull(BaseModel):
title: str
url: str
action: str
pull_request: Pull
# Initialize Webhook App
app = create_app()
# Register webhook handler:
# `pull_request` - name of an event to handle
# `PullRequestPayload` - webhook payload will be parsed into this model
@app.hooks.register('pull_request', PullRequestPayload)
async def handler(payload: PullRequestPayload) -> None:
print(f'New pull request {payload.pull_request.title}')
print(f' link: {payload.pull_request.url}')
print(f' author: {payload.sender.login}')
if __name__ == '__main__':
# start uvicorn server
uvicorn.run(app)
```
### Let's have detailed overview.
We start by defining payload [Model][5] to parse incoming [Pull Request Body][6].
```python
class PullRequestPayload(WebhookCommonPayload):
class Pull(BaseModel):
title: str
url: str
action: str
pull_request: Pull
```
In this example we only want to get `action`, `pull_request.title` and `pull_request.url` from payload.
By subclassing `WebhookCommonPayload` model will automatically get `sender`, `repository` and `organization` fields.
Next - we are creating ASGI app (based on FastAPI app)
```python
app = create_app()
```
Optionally we can provide here `secret_token` [Github Webhook secret][7]
```python
app = create_app(secret_token='super-secret-token')
```
And time to define our handler
```python
@app.hooks.register('pull_request', PullRequestPayload)
async def handler(payload: PullRequestPayload) -> None:
print(f'New pull request {payload.pull_request.title}')
print(f' link: {payload.pull_request.url}')
print(f' author: {payload.sender.login}')
```
We are using here `@app.hooks.register` deco, which accepts 2 arguments:
- `event: str` - name of webhook event
- `payload_cls: pydantic.BaseModel` - pydantic model class to parse request, subclassed from `pydantic.BaseModel`
or `WebhookCommonPayload`.
And our handler function may include the following (named) params:
```python
async def handler(payload: PullRequestPayload, headers: WebhookHeaders, query_params: QueryParams, background_tasks: BackgroundTasks) -> Optional[str]:
# `headers` will be WebhookHeaders model with Github Webhook headers parsed.
...
```
An example setup can be found in `example/server.py`.
## References:
[1]: https://developer.github.com/webhooks/
[2]: https://pypi.python.org/pypi/github-webhooks-framework
[3]: https://fastapi.tiangolo.com/
[4]: https://pydantic-docs.helpmanual.io/
[5]: https://pydantic-docs.helpmanual.io/usage/models/
[6]: https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request
[7]: https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks
## Development
1. Install local venv: `python -m venv .venv`
2. Activate: `. .venv/bin/activate`
3. Install deps with `pip install -r requirements.txt -r requirements-test.txt`
4. When done with packages: `./freeze-requirements.sh`
Raw data
{
"_id": null,
"home_page": null,
"name": "github-webhooks-framework2",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "github, webhooks, fastapi",
"author": "Karech",
"author_email": "Maurice Faber <morriz@idiotz.nl>",
"download_url": "https://files.pythonhosted.org/packages/63/8e/efbcdbceb2e9bcc4a8a6ccbab17ee3bf69e5d3f84994db6b95cd821489d6/github_webhooks_framework2-0.2.2.tar.gz",
"platform": null,
"description": "# Python GitHub Webhooks Framework\n\n**NOTE:** Forked from [github_webhooks](https://github.com/karech/github-webhooks) as I needed to access more things:\n\n- query params from incoming webhooks for identification\n- `background_tasks` to handle long running webhook actions.\n\nSimple and lightweight micro framework for quick integration with [GitHub\nwebhooks][1]. \nIt's based on [FastAPI][3] and [pydantic][4], nothing more! \nAsync and mypy friendly.\n\n[](https://github.com/morriz/github-webhooks/actions/workflows/ci.yml) \n[][2]\n\n## Installation\n\nJust add `github-webhooks-framework2` package. \nExample:\n\n- `pip install github-webhooks-framework2`\n- `poetry add github-webhooks-framework2`\n\n## Example\n\nCreate file `example.py` and copy next code:\n\n```python\nimport uvicorn\nfrom pydantic import BaseModel\n\nfrom github_webhooks import create_app\nfrom github_webhooks.schemas import WebhookCommonPayload\n\n\n# WebhookCommonPayload is based on pydantic.BaseModel\nclass PullRequestPayload(WebhookCommonPayload):\n class Pull(BaseModel):\n title: str\n url: str\n\n action: str\n pull_request: Pull\n\n\n# Initialize Webhook App\napp = create_app()\n\n\n# Register webhook handler:\n# `pull_request` - name of an event to handle\n# `PullRequestPayload` - webhook payload will be parsed into this model\n@app.hooks.register('pull_request', PullRequestPayload)\nasync def handler(payload: PullRequestPayload) -> None:\n print(f'New pull request {payload.pull_request.title}')\n print(f' link: {payload.pull_request.url}')\n print(f' author: {payload.sender.login}')\n\n\nif __name__ == '__main__':\n # start uvicorn server\n uvicorn.run(app)\n```\n\n### Let's have detailed overview.\n\nWe start by defining payload [Model][5] to parse incoming [Pull Request Body][6].\n\n```python\nclass PullRequestPayload(WebhookCommonPayload):\n class Pull(BaseModel):\n title: str\n url: str\n\n action: str\n pull_request: Pull\n```\n\nIn this example we only want to get `action`, `pull_request.title` and `pull_request.url` from payload. \nBy subclassing `WebhookCommonPayload` model will automatically get `sender`, `repository` and `organization` fields.\n\nNext - we are creating ASGI app (based on FastAPI app)\n\n```python\napp = create_app()\n```\n\nOptionally we can provide here `secret_token` [Github Webhook secret][7]\n\n```python\napp = create_app(secret_token='super-secret-token')\n```\n\nAnd time to define our handler\n\n```python\n@app.hooks.register('pull_request', PullRequestPayload)\nasync def handler(payload: PullRequestPayload) -> None:\n print(f'New pull request {payload.pull_request.title}')\n print(f' link: {payload.pull_request.url}')\n print(f' author: {payload.sender.login}')\n```\n\nWe are using here `@app.hooks.register` deco, which accepts 2 arguments:\n\n- `event: str` - name of webhook event\n- `payload_cls: pydantic.BaseModel` - pydantic model class to parse request, subclassed from `pydantic.BaseModel`\n or `WebhookCommonPayload`.\n\nAnd our handler function may include the following (named) params:\n\n```python\nasync def handler(payload: PullRequestPayload, headers: WebhookHeaders, query_params: QueryParams, background_tasks: BackgroundTasks) -> Optional[str]:\n # `headers` will be WebhookHeaders model with Github Webhook headers parsed.\n ...\n```\n\nAn example setup can be found in `example/server.py`.\n\n## References:\n\n[1]: https://developer.github.com/webhooks/\n[2]: https://pypi.python.org/pypi/github-webhooks-framework\n[3]: https://fastapi.tiangolo.com/\n[4]: https://pydantic-docs.helpmanual.io/\n[5]: https://pydantic-docs.helpmanual.io/usage/models/\n[6]: https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request\n[7]: https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks\n\n## Development\n\n1. Install local venv: `python -m venv .venv`\n2. Activate: `. .venv/bin/activate`\n3. Install deps with `pip install -r requirements.txt -r requirements-test.txt`\n4. When done with packages: `./freeze-requirements.sh`\n",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "GitHub Webhooks Framework",
"version": "0.2.2",
"project_urls": {
"Bug Tracker": "https://github.com/morriz/github-webhooks/issues",
"Origin": "https://github.com/karech/github-webhooks",
"Source Code": "https://github.com/morriz/github-webhooks",
"homepage": "https://github.com/morriz/github-webhooks"
},
"split_keywords": [
"github",
" webhooks",
" fastapi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "393e00f9353428be06a755d2f7bc7169c57d44ef1abaa2aafb668ac280f21f2d",
"md5": "a98ee7eeb6c6846c034139178b21b750",
"sha256": "70c385b264dad6f1e35f4ee5ec6fe8e68102141ba0de9351326e410df299ca97"
},
"downloads": -1,
"filename": "github_webhooks_framework2-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a98ee7eeb6c6846c034139178b21b750",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 20833,
"upload_time": "2024-12-12T14:40:47",
"upload_time_iso_8601": "2024-12-12T14:40:47.532457Z",
"url": "https://files.pythonhosted.org/packages/39/3e/00f9353428be06a755d2f7bc7169c57d44ef1abaa2aafb668ac280f21f2d/github_webhooks_framework2-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "638eefbcdbceb2e9bcc4a8a6ccbab17ee3bf69e5d3f84994db6b95cd821489d6",
"md5": "58e53d0d5f5f211eb1293e35756ca1d3",
"sha256": "e2949cea46ce60e8188327d94a41cdca1cf46b829814a8c80f13d5e0963014b9"
},
"downloads": -1,
"filename": "github_webhooks_framework2-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "58e53d0d5f5f211eb1293e35756ca1d3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 20362,
"upload_time": "2024-12-12T14:40:51",
"upload_time_iso_8601": "2024-12-12T14:40:51.433059Z",
"url": "https://files.pythonhosted.org/packages/63/8e/efbcdbceb2e9bcc4a8a6ccbab17ee3bf69e5d3f84994db6b95cd821489d6/github_webhooks_framework2-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-12 14:40:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "morriz",
"github_project": "github-webhooks",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "fastapi",
"specs": []
},
{
"name": "pydantic",
"specs": []
}
],
"lcname": "github-webhooks-framework2"
}
JSON
