# Carbon Webhooks Python Library
`carbon_webhooks_python` is a Python library designed to verify Carbon webhook events. This library provides a simple way to validate webhook signatures and ensure the authenticity of incoming requests.
## Features
- **Generate Signature**: Generate HMAC SHA256 signatures for webhook payloads.
- **Validate Signature**: Validate incoming webhook signatures to ensure they match the expected signature.
- **Extract Signature Header**: Parse and extract components from the Carbon-Signature header.
## Installation
You can install the library using pip:
```bash
pip install carbon-verifier
```
### `WebhookVerifier`
#### `__init__(signing_key: str)`
* `signing_key`: Your Carbon webhook signing key.
#### `generate_signature(timestamp: str, json_payload: str) -> str`
Generates a signature for the given timestamp and JSON payload.
* `timestamp`: The timestamp of the webhook event.
* `json_payload`: The JSON payload of the webhook event.
Returns the generated signature.
#### `validate_signature(received_sig: str, timestamp: str, payload: str) -> bool`
Validates the received signature against the generated signature.
* `received_sig`: The received signature to validate.
* `timestamp`: The timestamp of the webhook event.
* `payload`: The JSON payload of the webhook event.
Returns `true` if the signature is valid, otherwise `false`.
#### `extract_signature_header(header: str) -> Any`
Extracts the timestamp and signature from the Carbon-Signature header.
* `header`: The Carbon-Signature header.
Returns an object with the extracted signature parts.
## Example Usage
Here is an example demonstrating how to use the `carbon_verifier` library to verify a Carbon webhook:
```python
from carbon_verifier import WebhookVerifier
import json
# Initialize the verifier with your signing key
SIGNING_SECRET = 'aa76aee859f223451fd9bfb37ce893a0' # Replace with your actual signing key
verifier = WebhookVerifier(SIGNING_SECRET)
def verify_webhook(headers, payload):
carbon_signature = headers.get('Carbon-Signature')
if not carbon_signature:
return {'status': 'error', 'message': 'Missing Carbon-Signature header'}, 400
try:
timestamp, received_signature = WebhookVerifier.extract_signature_header(carbon_signature)
except ValueError:
return {'status': 'error', 'message': 'Invalid Carbon-Signature header format'}, 400
if not verifier.validate_signature(received_signature, timestamp, payload):
return {'status': 'error', 'message': 'Invalid signature'}, 400
data = json.loads(payload)
print("Received webhook data:", data)
# Handle the event
event_type = data.get('webhook_type')
if event_type == 'example_event':
# Process the event
print("Processing example_event")
return {'status': 'success'}, 200
# Hardcoded payload for example
payload_v1 = '{"payload": "{\\"webhook_type\\": \\"FILES_CREATED\\", \\"obj\\": {\\"object_type\\": \\"FILE_LIST\\", \\"object_id\\": [\\"46654\\"], \\"additional_information\\": \\"null\\"}, \\"customer_id\\": \\"satvik\\", \\"timestamp\\": \\"1721392406\\"}"}'
# Hardcoded header for example
headers = {
"Content-Type": "application/json",
"Carbon-Signature": "t=1721392406,v1=aa2273ab64bb9162e7e7983a9cd7ab9f90d686691b1fd25c577991ad42c53fc1",
"Carbon-Signature-Compact": "t=1721392406,v2=42a86d4083fee090b5a0800a91e82fb389f0bed4da757d07ee8ba97485194e59"
}
result, status_code = verify_webhook(headers, payload_v1)
print(f"Verification Result: {result}, Status Code: {status_code}")
Raw data
{
"_id": null,
"home_page": "https://github.com/Carbon-for-Developers/webhook-library.git",
"name": "carbon-verifier",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "carbon",
"author_email": "team@carbon.ai",
"download_url": "https://files.pythonhosted.org/packages/e7/f0/6d6265032b1238cf7d9da679d72cb7c4266cf17a18bfe5276d5b391f8610/carbon_verifier-0.1.2.tar.gz",
"platform": null,
"description": "# Carbon Webhooks Python Library\n\n`carbon_webhooks_python` is a Python library designed to verify Carbon webhook events. This library provides a simple way to validate webhook signatures and ensure the authenticity of incoming requests.\n\n## Features\n\n- **Generate Signature**: Generate HMAC SHA256 signatures for webhook payloads.\n- **Validate Signature**: Validate incoming webhook signatures to ensure they match the expected signature.\n- **Extract Signature Header**: Parse and extract components from the Carbon-Signature header.\n\n## Installation\n\nYou can install the library using pip:\n\n```bash\npip install carbon-verifier\n```\n\n### `WebhookVerifier`\n\n#### `__init__(signing_key: str)`\n\n* `signing_key`: Your Carbon webhook signing key.\n\n#### `generate_signature(timestamp: str, json_payload: str) -> str`\n\nGenerates a signature for the given timestamp and JSON payload.\n\n* `timestamp`: The timestamp of the webhook event.\n* `json_payload`: The JSON payload of the webhook event.\n\nReturns the generated signature.\n\n#### `validate_signature(received_sig: str, timestamp: str, payload: str) -> bool`\n\nValidates the received signature against the generated signature.\n\n* `received_sig`: The received signature to validate.\n* `timestamp`: The timestamp of the webhook event.\n* `payload`: The JSON payload of the webhook event.\n\nReturns `true` if the signature is valid, otherwise `false`.\n\n#### `extract_signature_header(header: str) -> Any`\n\nExtracts the timestamp and signature from the Carbon-Signature header.\n\n* `header`: The Carbon-Signature header.\n\nReturns an object with the extracted signature parts.\n\n## Example Usage\n\nHere is an example demonstrating how to use the `carbon_verifier` library to verify a Carbon webhook:\n\n```python\nfrom carbon_verifier import WebhookVerifier\nimport json\n\n# Initialize the verifier with your signing key\nSIGNING_SECRET = 'aa76aee859f223451fd9bfb37ce893a0' # Replace with your actual signing key\nverifier = WebhookVerifier(SIGNING_SECRET)\n\ndef verify_webhook(headers, payload):\n carbon_signature = headers.get('Carbon-Signature')\n if not carbon_signature:\n return {'status': 'error', 'message': 'Missing Carbon-Signature header'}, 400\n\n try:\n timestamp, received_signature = WebhookVerifier.extract_signature_header(carbon_signature)\n except ValueError:\n return {'status': 'error', 'message': 'Invalid Carbon-Signature header format'}, 400\n\n if not verifier.validate_signature(received_signature, timestamp, payload):\n return {'status': 'error', 'message': 'Invalid signature'}, 400\n\n data = json.loads(payload)\n print(\"Received webhook data:\", data)\n\n # Handle the event\n event_type = data.get('webhook_type')\n if event_type == 'example_event':\n # Process the event\n print(\"Processing example_event\")\n\n return {'status': 'success'}, 200\n\n# Hardcoded payload for example\npayload_v1 = '{\"payload\": \"{\\\\\"webhook_type\\\\\": \\\\\"FILES_CREATED\\\\\", \\\\\"obj\\\\\": {\\\\\"object_type\\\\\": \\\\\"FILE_LIST\\\\\", \\\\\"object_id\\\\\": [\\\\\"46654\\\\\"], \\\\\"additional_information\\\\\": \\\\\"null\\\\\"}, \\\\\"customer_id\\\\\": \\\\\"satvik\\\\\", \\\\\"timestamp\\\\\": \\\\\"1721392406\\\\\"}\"}'\n\n# Hardcoded header for example\nheaders = {\n \"Content-Type\": \"application/json\",\n \"Carbon-Signature\": \"t=1721392406,v1=aa2273ab64bb9162e7e7983a9cd7ab9f90d686691b1fd25c577991ad42c53fc1\",\n \"Carbon-Signature-Compact\": \"t=1721392406,v2=42a86d4083fee090b5a0800a91e82fb389f0bed4da757d07ee8ba97485194e59\"\n}\n\nresult, status_code = verify_webhook(headers, payload_v1)\nprint(f\"Verification Result: {result}, Status Code: {status_code}\")\n",
"bugtrack_url": null,
"license": null,
"summary": "A library to verify Carbon webhook events",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/Carbon-for-Developers/webhook-library.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "05117b4f8d7f4e589a6dded294e2c3e6bdbd3074e48d42355bf4dc1cd867f7c6",
"md5": "9ddbdafdd70fab1da298be04e478e031",
"sha256": "10930cf69d6dd28f32b6cd21df91331fe318a6c861ba1fdc04257d0de342e7da"
},
"downloads": -1,
"filename": "carbon_verifier-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9ddbdafdd70fab1da298be04e478e031",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 3543,
"upload_time": "2024-08-02T14:28:38",
"upload_time_iso_8601": "2024-08-02T14:28:38.138336Z",
"url": "https://files.pythonhosted.org/packages/05/11/7b4f8d7f4e589a6dded294e2c3e6bdbd3074e48d42355bf4dc1cd867f7c6/carbon_verifier-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e7f06d6265032b1238cf7d9da679d72cb7c4266cf17a18bfe5276d5b391f8610",
"md5": "ef734442bbe1ae78491f5c09c9447753",
"sha256": "c4d9586a60c0458268c1fc8723edb85a11c32981a9d9618607a3be54cbe09a82"
},
"downloads": -1,
"filename": "carbon_verifier-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "ef734442bbe1ae78491f5c09c9447753",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 3161,
"upload_time": "2024-08-02T14:28:40",
"upload_time_iso_8601": "2024-08-02T14:28:40.300539Z",
"url": "https://files.pythonhosted.org/packages/e7/f0/6d6265032b1238cf7d9da679d72cb7c4266cf17a18bfe5276d5b391f8610/carbon_verifier-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-02 14:28:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Carbon-for-Developers",
"github_project": "webhook-library",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "carbon-verifier"
}
JSON
