| Name | formsg JSON |
| Version |
0.1.8
JSON |
| download |
| home_page | |
| Summary | A Python SDK for handling FormSG webhooks. |
| upload_time | 2023-06-15 18:03:47 |
| maintainer | |
| docs_url | None |
| author | 5 Health Inc |
| requires_python | >=3.9,<4.0 |
| license | |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# FormSG Python SDK
[](https://pypi.python.org/pypi/formsg/)
[](https://pypi.python.org/pypi/formsg/)
[](https://pypi.python.org/pypi/formsg/)
[](https://pypi.python.org/pypi/formsg/)
[](https://pypi.python.org/pypi/formsg/)
This SDK provides convenient utilities for verifying FormSG webhooks and decrypting submissions in Python and Flask or Django.
## Installation
```bash
pip install formsg
```
## Usage
The SDK provides two main utility functions for handling FormSG webhook:
- [`webhook_uri: str, signature_header: str, signature_expiry_seconds: float = 60) -> Mapping[str, Any]`](formsg/utils.py) verifies that the incoming webhook's signature is valid based on the FormSG production public key.
It raises a `nacl.exceptions.BadSignatureError` if the signature is invalid.
The signature header is usually found in the `X-FormSG-Signature` header.
Details on how the signature is constructed can be found [here](https://github.com/opengovsg/formsg-javascript-sdk/#verifying-signatures-manually).
- [`decrypt_content(body: Mapping[str, Any], secret_key: str) -> Mapping[str, Any]`](formsg/utils.py) will decrypt the encrypted content using the given Base-64 encoded secret key.
`body` is expected to be a dictionary-like object.
- [`decrypt_attachment(body: Mapping[str, Any], field_id: str, secret_key: str) -> bytes`](formsg/utils.py) will download and decrypt the encrypted attachment for a `field` and using the given Base-64 encoded secret key. `body` is expected to be a dictionary-like object.
For convenience, the SDK implements a [`decrypt_django_request`](formsg/django.py) and [`decrypt_flask_request`](formsg/flask.py) which returns the decrypted FormSG content from a Django/Flask request object directly.
### Example with Flask
```python
from formsg.flask import decrypt_flask_request
from flask import Flask
from flask import jsonify
from flask import request
app = Flask(__name__)
@app.route('/formsg_webhook', methods=['POST'])
def formsg_webhook():
decrypted = decrypt_flask_request(
request,
secret_key='xxx',
webhook_uri='https://xxx.ngrok.io/formsg_webhook', # we use ngrok to test our webhooks locally
)
return jsonify(decrypted)
#end def
if __name__ == '__main__':
app.run(debug=True)
#end if
```
## Contributions
If you find any issues or would like to contribute improvements, please feel free to raise them in this repository directly.
Raw data
{
"_id": null,
"home_page": "",
"name": "formsg",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "5 Health Inc",
"author_email": "engineers@botmd.io",
"download_url": "https://files.pythonhosted.org/packages/96/82/1e3861f2e74c29cf5aa7d98a7580bd1f10f9f55744973c087ba053ce5383/formsg-0.1.8.tar.gz",
"platform": null,
"description": "# FormSG Python SDK\n\n[](https://pypi.python.org/pypi/formsg/)\n[](https://pypi.python.org/pypi/formsg/)\n[](https://pypi.python.org/pypi/formsg/)\n[](https://pypi.python.org/pypi/formsg/)\n[](https://pypi.python.org/pypi/formsg/)\n\nThis SDK provides convenient utilities for verifying FormSG webhooks and decrypting submissions in Python and Flask or Django.\n\n## Installation\n\n```bash\npip install formsg\n```\n\n## Usage\n\nThe SDK provides two main utility functions for handling FormSG webhook:\n\n- [`webhook_uri: str, signature_header: str, signature_expiry_seconds: float = 60) -> Mapping[str, Any]`](formsg/utils.py) verifies that the incoming webhook's signature is valid based on the FormSG production public key.\nIt raises a `nacl.exceptions.BadSignatureError` if the signature is invalid.\nThe signature header is usually found in the `X-FormSG-Signature` header.\nDetails on how the signature is constructed can be found [here](https://github.com/opengovsg/formsg-javascript-sdk/#verifying-signatures-manually).\n\n- [`decrypt_content(body: Mapping[str, Any], secret_key: str) -> Mapping[str, Any]`](formsg/utils.py) will decrypt the encrypted content using the given Base-64 encoded secret key.\n`body` is expected to be a dictionary-like object.\n\n- [`decrypt_attachment(body: Mapping[str, Any], field_id: str, secret_key: str) -> bytes`](formsg/utils.py) will download and decrypt the encrypted attachment for a `field` and using the given Base-64 encoded secret key. `body` is expected to be a dictionary-like object.\n\nFor convenience, the SDK implements a [`decrypt_django_request`](formsg/django.py) and [`decrypt_flask_request`](formsg/flask.py) which returns the decrypted FormSG content from a Django/Flask request object directly.\n\n### Example with Flask\n\n```python\nfrom formsg.flask import decrypt_flask_request\n\nfrom flask import Flask\nfrom flask import jsonify\nfrom flask import request\n\napp = Flask(__name__)\n\n\n@app.route('/formsg_webhook', methods=['POST'])\ndef formsg_webhook():\n decrypted = decrypt_flask_request(\n request,\n secret_key='xxx',\n webhook_uri='https://xxx.ngrok.io/formsg_webhook', # we use ngrok to test our webhooks locally\n )\n\n return jsonify(decrypted)\n#end def\n\n\nif __name__ == '__main__':\n app.run(debug=True)\n#end if\n```\n\n## Contributions\n\nIf you find any issues or would like to contribute improvements, please feel free to raise them in this repository directly.\n",
"bugtrack_url": null,
"license": "",
"summary": "A Python SDK for handling FormSG webhooks.",
"version": "0.1.8",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8001408156822d2b02630b5784c9cbab5787875bbb1914cde9f08c64a1119f54",
"md5": "78f99247ae46f4eee1c2d4323008d5af",
"sha256": "42b908ae8a94ac658cf95c824e96a82a366e5ae5e52f3fe3e476161bab0a1cbc"
},
"downloads": -1,
"filename": "formsg-0.1.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "78f99247ae46f4eee1c2d4323008d5af",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 5495,
"upload_time": "2023-06-15T18:03:46",
"upload_time_iso_8601": "2023-06-15T18:03:46.221913Z",
"url": "https://files.pythonhosted.org/packages/80/01/408156822d2b02630b5784c9cbab5787875bbb1914cde9f08c64a1119f54/formsg-0.1.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "96821e3861f2e74c29cf5aa7d98a7580bd1f10f9f55744973c087ba053ce5383",
"md5": "f93af9e7156be8f153ad5b30a45735a5",
"sha256": "8beee423bedc34636e23fddbc55723b9448adec1b1d131b6ca264609fa5c7930"
},
"downloads": -1,
"filename": "formsg-0.1.8.tar.gz",
"has_sig": false,
"md5_digest": "f93af9e7156be8f153ad5b30a45735a5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 4427,
"upload_time": "2023-06-15T18:03:47",
"upload_time_iso_8601": "2023-06-15T18:03:47.457979Z",
"url": "https://files.pythonhosted.org/packages/96/82/1e3861f2e74c29cf5aa7d98a7580bd1f10f9f55744973c087ba053ce5383/formsg-0.1.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-15 18:03:47",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "formsg"
}
