# Webhook Guardian 🛡️
[](https://badge.fury.io/py/webhook-guardian)
[](https://python.org)
[](LICENSE)
[](tests/)
A beginner-friendly Python library for secure webhook handling and validation.
## 🎯 **What is Webhook Guardian?**
Webhook Guardian is a security-focused library that helps developers safely receive and validate webhooks from external services. It protects against common webhook security vulnerabilities like replay attacks, signature spoofing, and unauthorized requests.
## 🔒 **Security Features**
- **HMAC Signature Verification** - Verify webhooks are from trusted sources
- **Replay Attack Prevention** - Timestamp validation to prevent reused requests
- **Rate Limiting** - Protect against webhook spam and abuse
- **IP Whitelist Validation** - Only accept webhooks from authorized IPs
- **Request Size Limits** - Prevent oversized payload attacks
- **Comprehensive Logging** - Track and monitor webhook activity
## 🚀 **Quick Start**
### Installation
```bash
pip install webhook-guardian
```
### Basic Usage
```python
from webhook_guardian import WebhookValidator
# Initialize the validator with your secret
validator = WebhookValidator(
secret="your-webhook-secret",
tolerance_seconds=300 # Allow 5 minutes clock skew
)
# In your webhook endpoint
def handle_webhook(request):
# Validate the webhook
if validator.verify_request(
payload=request.body,
signature=request.headers.get('X-Hub-Signature-256'),
timestamp=request.headers.get('X-Timestamp')
):
# Process the webhook safely
process_webhook_data(request.body)
return {"status": "success"}
else:
# Reject invalid webhook
return {"error": "Invalid webhook"}, 401
```
### Signature Algorithm Examples
#### HMAC-SHA1
```python
validator = WebhookValidator(secret="your-webhook-secret")
signature = validator._compute_signature(payload, algorithm="sha1")
is_valid = validator.verify_signature(payload, signature)
```
#### HMAC-SHA512
```python
validator = WebhookValidator(secret="your-webhook-secret")
signature = validator._compute_signature(payload, algorithm="sha512")
is_valid = validator.verify_signature(payload, signature)
```
#### Ed25519
```python
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
# Generate key pair (for demonstration; use secure key management in production)
private_key = Ed25519PrivateKey.generate()
public_key = private_key.public_key()
public_bytes = public_key.public_bytes(
encoding=serialization.Encoding.Raw,
format=serialization.PublicFormat.Raw
)
payload = b"example webhook payload"
signature_bytes = private_key.sign(payload)
signature = f"ed25519={signature_bytes.hex()}"
# Validator with Ed25519 public key
validator = WebhookValidator(secret="irrelevant-for-ed25519", ed25519_public_key=public_bytes)
is_valid = validator.verify_signature(payload, signature)
```
### Advanced Configuration
```python
from webhook_guardian import WebhookGuardian
# Full-featured webhook handler
guardian = WebhookGuardian(
secret="your-secret",
allowed_ips=["192.168.1.100", "10.0.0.0/8"],
max_payload_size=1024 * 1024, # 1MB limit
rate_limit={"requests": 100, "window": 3600}, # 100 req/hour
enable_logging=True
)
# Validate with all security checks
result = guardian.validate_webhook(request)
if result.is_valid:
process_webhook(request.body)
else:
logger.warning(f"Invalid webhook: {result.error_message}")
```
## 📚 **Documentation**
- [Security Best Practices](docs/security.md)
- [API Reference](docs/api.md)
- [Examples](examples/)
- [Contributing Guide](CONTRIBUTING.md)
## 🧪 **Testing**
```bash
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run tests with coverage
pytest --cov=webhook_guardian
```
## 🛠️ **Development**
```bash
# Clone the repository
git clone https://github.com/rebzie22/webhook-guardian.git
cd webhook-guardian
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode
pip install -e ".[dev]"
# Install pre-commit hooks
pre-commit install
```
## 🤝 **Contributing**
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
## 📄 **License**
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 **Acknowledgments**
- Inspired by common webhook security vulnerabilities
- Built for developers who want to handle webhooks securely
- Designed with beginners in mind
## 📞 **Support**
- [Documentation](docs/)
- [Issue Tracker](https://github.com/rebzie22/webhook-guardian/issues)
- [Discussions](https://github.com/rebzie22/webhook-guardian/discussions)
Raw data
{
"_id": null,
"home_page": "https://github.com/rebzie22/webhook-guardian",
"name": "webhook-guardian",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Jordan Guck <your.email@example.com>",
"keywords": "webhook, security, validation, hmac, cryptography",
"author": "Jordan Guck",
"author_email": "Jordan Guck <your.email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/f2/cd/82533a04aae665d92df1b328cfc7cce2ee51923603db1d25339d4c6147eb/webhook_guardian-0.1.1.tar.gz",
"platform": null,
"description": "# Webhook Guardian \ud83d\udee1\ufe0f\r\n\r\n[](https://badge.fury.io/py/webhook-guardian)\r\n[](https://python.org)\r\n[](LICENSE)\r\n[](tests/)\r\n\r\nA beginner-friendly Python library for secure webhook handling and validation.\r\n\r\n## \ud83c\udfaf **What is Webhook Guardian?**\r\n\r\nWebhook Guardian is a security-focused library that helps developers safely receive and validate webhooks from external services. It protects against common webhook security vulnerabilities like replay attacks, signature spoofing, and unauthorized requests.\r\n\r\n## \ud83d\udd12 **Security Features**\r\n\r\n- **HMAC Signature Verification** - Verify webhooks are from trusted sources\r\n- **Replay Attack Prevention** - Timestamp validation to prevent reused requests\r\n- **Rate Limiting** - Protect against webhook spam and abuse\r\n- **IP Whitelist Validation** - Only accept webhooks from authorized IPs\r\n- **Request Size Limits** - Prevent oversized payload attacks\r\n- **Comprehensive Logging** - Track and monitor webhook activity\r\n\r\n## \ud83d\ude80 **Quick Start**\r\n\r\n### Installation\r\n\r\n```bash\r\npip install webhook-guardian\r\n```\r\n\r\n### Basic Usage\r\n\r\n```python\r\nfrom webhook_guardian import WebhookValidator\r\n\r\n# Initialize the validator with your secret\r\nvalidator = WebhookValidator(\r\n secret=\"your-webhook-secret\",\r\n tolerance_seconds=300 # Allow 5 minutes clock skew\r\n)\r\n\r\n# In your webhook endpoint\r\ndef handle_webhook(request):\r\n # Validate the webhook\r\n if validator.verify_request(\r\n payload=request.body,\r\n signature=request.headers.get('X-Hub-Signature-256'),\r\n timestamp=request.headers.get('X-Timestamp')\r\n ):\r\n # Process the webhook safely\r\n process_webhook_data(request.body)\r\n return {\"status\": \"success\"}\r\n else:\r\n # Reject invalid webhook\r\n return {\"error\": \"Invalid webhook\"}, 401\r\n```\r\n\r\n\r\n### Signature Algorithm Examples\r\n\r\n#### HMAC-SHA1\r\n```python\r\nvalidator = WebhookValidator(secret=\"your-webhook-secret\")\r\nsignature = validator._compute_signature(payload, algorithm=\"sha1\")\r\nis_valid = validator.verify_signature(payload, signature)\r\n```\r\n\r\n#### HMAC-SHA512\r\n```python\r\nvalidator = WebhookValidator(secret=\"your-webhook-secret\")\r\nsignature = validator._compute_signature(payload, algorithm=\"sha512\")\r\nis_valid = validator.verify_signature(payload, signature)\r\n```\r\n\r\n#### Ed25519\r\n```python\r\nfrom cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey\r\n\r\n# Generate key pair (for demonstration; use secure key management in production)\r\nprivate_key = Ed25519PrivateKey.generate()\r\npublic_key = private_key.public_key()\r\npublic_bytes = public_key.public_bytes(\r\n encoding=serialization.Encoding.Raw,\r\n format=serialization.PublicFormat.Raw\r\n)\r\n\r\npayload = b\"example webhook payload\"\r\nsignature_bytes = private_key.sign(payload)\r\nsignature = f\"ed25519={signature_bytes.hex()}\"\r\n\r\n# Validator with Ed25519 public key\r\nvalidator = WebhookValidator(secret=\"irrelevant-for-ed25519\", ed25519_public_key=public_bytes)\r\nis_valid = validator.verify_signature(payload, signature)\r\n```\r\n\r\n### Advanced Configuration\r\n\r\n```python\r\nfrom webhook_guardian import WebhookGuardian\r\n\r\n# Full-featured webhook handler\r\nguardian = WebhookGuardian(\r\n secret=\"your-secret\",\r\n allowed_ips=[\"192.168.1.100\", \"10.0.0.0/8\"],\r\n max_payload_size=1024 * 1024, # 1MB limit\r\n rate_limit={\"requests\": 100, \"window\": 3600}, # 100 req/hour\r\n enable_logging=True\r\n)\r\n\r\n# Validate with all security checks\r\nresult = guardian.validate_webhook(request)\r\nif result.is_valid:\r\n process_webhook(request.body)\r\nelse:\r\n logger.warning(f\"Invalid webhook: {result.error_message}\")\r\n```\r\n\r\n## \ud83d\udcda **Documentation**\r\n\r\n- [Security Best Practices](docs/security.md)\r\n- [API Reference](docs/api.md)\r\n- [Examples](examples/)\r\n- [Contributing Guide](CONTRIBUTING.md)\r\n\r\n## \ud83e\uddea **Testing**\r\n\r\n```bash\r\n# Install development dependencies\r\npip install -e \".[dev]\"\r\n\r\n# Run tests\r\npytest\r\n\r\n# Run tests with coverage\r\npytest --cov=webhook_guardian\r\n```\r\n\r\n## \ud83d\udee0\ufe0f **Development**\r\n\r\n```bash\r\n# Clone the repository\r\ngit clone https://github.com/rebzie22/webhook-guardian.git\r\ncd webhook-guardian\r\n\r\n# Create virtual environment\r\npython -m venv venv\r\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\r\n\r\n# Install in development mode\r\npip install -e \".[dev]\"\r\n\r\n# Install pre-commit hooks\r\npre-commit install\r\n```\r\n\r\n## \ud83e\udd1d **Contributing**\r\n\r\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\r\n\r\n## \ud83d\udcc4 **License**\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83d\ude4f **Acknowledgments**\r\n\r\n- Inspired by common webhook security vulnerabilities\r\n- Built for developers who want to handle webhooks securely\r\n- Designed with beginners in mind\r\n\r\n## \ud83d\udcde **Support**\r\n\r\n- [Documentation](docs/)\r\n- [Issue Tracker](https://github.com/rebzie22/webhook-guardian/issues)\r\n- [Discussions](https://github.com/rebzie22/webhook-guardian/discussions)\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A security-focused Python library for validating and handling webhooks safely",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/rebzie22/webhook-guardian/issues",
"Changelog": "https://github.com/rebzie22/webhook-guardian/releases",
"Documentation": "https://github.com/rebzie22/webhook-guardian#readme",
"Homepage": "https://github.com/rebzie22/webhook-guardian",
"Repository": "https://github.com/rebzie22/webhook-guardian.git"
},
"split_keywords": [
"webhook",
" security",
" validation",
" hmac",
" cryptography"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e57526898b1cf913178c5745dae2465b72025ec1031760f46ed9c4ddecba0523",
"md5": "9947f63be455f40b666b9f48a682b4e0",
"sha256": "11025bcf652b9f7d3b4258a21b7f26d894b712954f8018f7699b9b2a80bb2e8e"
},
"downloads": -1,
"filename": "webhook_guardian-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9947f63be455f40b666b9f48a682b4e0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11759,
"upload_time": "2025-07-24T00:08:49",
"upload_time_iso_8601": "2025-07-24T00:08:49.128180Z",
"url": "https://files.pythonhosted.org/packages/e5/75/26898b1cf913178c5745dae2465b72025ec1031760f46ed9c4ddecba0523/webhook_guardian-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f2cd82533a04aae665d92df1b328cfc7cce2ee51923603db1d25339d4c6147eb",
"md5": "56e74bee84fd60011256091877cb5c1a",
"sha256": "95038a415998f1299af518b3bcdd039b724e7655c0f92b801d1cd4da2e7f8367"
},
"downloads": -1,
"filename": "webhook_guardian-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "56e74bee84fd60011256091877cb5c1a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 29236,
"upload_time": "2025-07-24T00:08:50",
"upload_time_iso_8601": "2025-07-24T00:08:50.214030Z",
"url": "https://files.pythonhosted.org/packages/f2/cd/82533a04aae665d92df1b328cfc7cce2ee51923603db1d25339d4c6147eb/webhook_guardian-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 00:08:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rebzie22",
"github_project": "webhook-guardian",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "cryptography",
"specs": [
[
">=",
"3.4.8"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.25.1"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
">=",
"2.8.2"
]
]
}
],
"lcname": "webhook-guardian"
}
JSON
