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:
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:
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}")
Metadata
Release files for carbon-verifier 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| carbon_verifier-0.1.2.tar.gz | 3.2 kB | Without provenance | Details for carbon_verifier-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| carbon_verifier-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for carbon_verifier-0.1.2-py3-none-any.whl |
Total release size: 6.7 kB
Release files / carbon_verifier-0.1.2.tar.gz
| Download URL | carbon_verifier-0.1.2.tar.gz |
|---|---|
| Size | 3.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c4d9586a60c0458268c1fc8723edb85a11c32981a9d9618607a3be54cbe09a82
|
|
BLAKE2b-256 checksum How to use checksums |
e7f06d6265032b1238cf7d9da679d72cb7c4266cf17a18bfe5276d5b391f8610
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.1.1 CPython/3.12.4
|
Release files / carbon_verifier-0.1.2-py3-none-any.whl
| Download URL | carbon_verifier-0.1.2-py3-none-any.whl |
|---|---|
| Size | 3.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
10930cf69d6dd28f32b6cd21df91331fe318a6c861ba1fdc04257d0de342e7da
|
|
BLAKE2b-256 checksum How to use checksums |
05117b4f8d7f4e589a6dded294e2c3e6bdbd3074e48d42355bf4dc1cd867f7c6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.1.1 CPython/3.12.4
|
Security for carbon-verifier 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.