Install & Compatibility
Where this runs
tested against v1.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.022s · 17.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.022s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Webhook
✓ from standardwebhooks import Webhook
✗ import standardwebhooks.Webhook
The primary Webhook class is directly available from the top-level package.
WebhookVerificationError
✓ from standardwebhooks import WebhookVerificationError
Common error class for handling failed webhook verifications.
WebhookSigningError
✓ from standardwebhooks import WebhookSigningError
Common error class for handling failed webhook signing.
This quickstart demonstrates how to initialize the `Webhook` class with a secret and verify an incoming webhook request. It shows the expected input types (headers as dict, body as bytes) and how to handle potential `WebhookVerificationError` exceptions, which are critical for secure webhook processing. Remember to load your secret securely from environment variables or a secret manager and ensure it's provided as bytes.
import os
from standardwebhooks import Webhook, WebhookVerificationError
# In a real application, the secret should be securely loaded from environment variables or a secret store.
# It MUST be bytes.
WEBHOOK_SECRET = os.environ.get('STANDARDWEBHOOKS_SECRET', 'whsec_testsecretforlocaldevelopmentonly').encode('utf-8')
# Example incoming webhook data (replace with actual request data)
headers = {
'Webhook-Id': 'msg_00000000000000000000000000',
'Webhook-Timestamp': '2024-04-10T12:00:00Z',
'Webhook-Signature': 'v1,sig_00000000000000000000000000',
'Content-Type': 'application/json'
}
body = b'{"key": "value"}' # Body must be bytes
# Initialize the Webhook handler with your secret
webhook = Webhook(WEBHOOK_SECRET)
try:
# Verify the incoming webhook
# In a web framework, you would pass request.headers and request.body
verified_data = webhook.verify(headers=headers, body=body)
print("Webhook verified successfully!")
print("Payload:", verified_data)
except WebhookVerificationError as e:
print(f"Webhook verification failed: {e}")
# Important: Log the error but do not expose details to the client.
# Return a 400 or 401 status code.
except Exception as e:
print(f"An unexpected error occurred: {e}")
# To simulate a successful verification, you'd need a valid signature for the given secret, body, id, and timestamp.
# The example above uses placeholder values for demonstration.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'standardwebhooks'
The 'standardwebhooks' library has not been installed in the Python environment where the script is being executed.
fixInstall the library using pip: `pip install standardwebhooks`
ValueError: Invalid secret: must start with 'whsec_'
The webhook secret provided to `WebhookReceiver` or `WebhookVerifier` does not begin with the required `whsec_` prefix.
fixEnsure the secret string is correctly formatted, typically obtained from the webhook provider, and includes the `whsec_` prefix, e.g., `WebhookReceiver(secret='whsec_your_actual_secret_value')`.
standardwebhooks.exceptions.SignatureVerificationError
The signature provided in the webhook header ('webhook-signature') does not match the computed signature for the received payload, indicating a tampered or invalid webhook.
fixVerify that the secret used for initialization (`WebhookReceiver(secret=...)`) is correct and matches the secret configured for the webhook sender. Ensure the raw request body and headers are passed to the `receive` method exactly as received, without any modification.
standardwebhooks.exceptions.DecryptionError
The webhook payload could not be decrypted, likely due to an incorrect encryption key (secret) or a corrupted encrypted message.
fixConfirm that the secret used by `WebhookReceiver` or `WebhookVerifier` is the correct `whsec_` secret for encrypted webhooks and that the payload is the raw, encrypted content received.
standardwebhooks.exceptions.ReplayError
A webhook with the same ID and timestamp has been processed recently, indicating a potential replay attack or a duplicate delivery attempt, as detected by the replay protection mechanism.
fixThis error signals a successful detection of a replay. While generally a security measure, if legitimate duplicates are expected, your application logic should handle them appropriately. Ensure your replay protection store (e.g., `RedisReplayProtectionStore`) is correctly configured and accessible.
Upgrade
Version history
1.1.0latest on PyPI · released Jul 21, 2026
Audit
Dependencies
cryptographyrequiredUsed for cryptographic operations like signature verification and encryption.
python-joserequiredUsed for JSON Web Signatures (JWS) and JSON Web Encryption (JWE) components of the specification.