Skip to content

Webhook Security Guide

Webhook Security Guide

Scope: Shopify webhooks in the Python SaaS template. Stripe guidance is optional and referenced from the commerce feature module.

Threats

Replay attacks: resend valid requests
Spoofing: fake webhook events
Tampering: modify payload in transit
DDoS: flood the endpoint

Shopify Signature Verification

Shopify sends an HMAC-SHA256 signature in X-Shopify-Hmac-SHA256.

Python SaaS implementation:

Handler: templates/python-saas/features/commerce/src/ui/api/webhooks.py
Verification: templates/python-saas/features/commerce/src/infrastructure/commerce/shopify_adapter.py

Verify signature before any processing and return 401 if invalid.

Stripe Signature Verification (Optional)

Stripe signatures are verified in the feature module:

features/python-saas/commerce/src/ui/api/stripe_webhooks.py
features/python-saas/commerce/src/infrastructure/commerce/stripe_adapter.py

If Stripe is enabled in the template, port these files and verify signatures before processing.

Replay Protection

Stripe provides timestamp verification.
For Shopify, a TTL-based dedupe key is used when X-Shopify-Webhook-Id is present.
Fallback uses a payload hash if the webhook id header is missing.

Rate Limiting

Apply rate limiting at the reverse proxy or middleware layer.

Use NGINX, API gateway, or a FastAPI middleware.
Keep limits high enough for retries and bursts.

Logging Rules

Log event type, timestamp, and status.
Redact PII before logging. Use LogRedactor.

Checklist

Incident Response

If webhook security is compromised:

Rotate webhook secrets.
Review logs for suspicious activity.
Update firewall rules if needed.
Document the incident and fixes.

References

PII guide: docs/compliance/PII_HANDLING_GUIDE.md
GDPR checklist: docs/compliance/GDPR_CHECKLIST.md