Verify the Masnet signature in Python

Requirements in Masnet

Before configuring the receiving system, prepare the destination in Masnet. The steps are the same for every system.

1. Open Company › Integrations (the Spanish interface labels it Empresa › Integraciones), go to the Destinations tab and select New destination. If the integration has no authorized data yet, Masnet asks you to authorize it first.
2. In Destination address (https) enter the receiver public URL. It must be https, port 443 or 8443 and a public DNS name: user information in the URL, fragments, IP addresses and internal names are not accepted. A query string is allowed; Masnet treats the whole URL as a credential.
3. In Format choose Standard JSON (application/json) or Structured CloudEvents (application/cloudevents+json). The event content is the same; see Webhooks.
4. Select Create destination. Masnet shows the signing secret (whsec_…) only once. Store it immediately in the receiver secret store; it cannot be read again.
5. Select Test destination and then Send test. The integration is activated only after a successful test; then use Activate destination.

Data the verifier needs

• The destination signing secret (whsec_…), stored outside the code.
• The exact body received, uninterpreted. In Flask use request.get_data(); in FastAPI, await request.body(); do not use the already parsed JSON.
• The webhook-id, webhook-timestamp and webhook-signature headers.
• A clock tolerance of 5 minutes, which is what the Standard Webhooks libraries apply and what is recommended for the receiver.

The signature is v1, followed by base64(HMAC-SHA256) computed with the binary key obtained by base64-decoding what follows whsec_, over the bytes webhook-id + . + webhook-timestamp + . + the exact body. Always verify over the received bytes, before parsing the JSON.

With the standardwebhooks package

Install it with pip install standardwebhooks.

# pip install standardwebhooks
from standardwebhooks import Webhook, WebhookVerificationError


def verify(secret: str, headers: dict, raw_body: bytes) -> bool:
    """`raw_body` is the unparsed request body; the library enforces a 5 minute tolerance."""
    try:
        Webhook(secret).verify(raw_body, headers)
        return True
    except (WebhookVerificationError, ValueError):  # ValueError: malformed base64 in the header
        return False

Without dependencies

The function compares in constant time and accepts any of the signatures in the header.

import base64
import hashlib
import hmac
import time


def verify(secret: str, headers: dict, raw_body: bytes, now: float | None = None, tolerance: int = 300) -> bool:
    """Verify a Masnet webhook with the standard library. `raw_body` is the exact bytes received."""
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signatures = headers.get("webhook-signature")
    if not msg_id or not signatures or not (timestamp or "").isdigit():
        return False
    if abs((time.time() if now is None else now) - int(timestamp)) > tolerance:
        return False

    key = base64.b64decode(secret.removeprefix("whsec_"))
    expected = hmac.new(key, f"{msg_id}.{timestamp}.".encode() + raw_body, hashlib.sha256).digest()

    # During a rotation the header carries two signatures separated by a space; any match is valid.
    for part in signatures.split(" "):
        version, _, value = part.partition(",")
        if version == "v1" and value:
            try:
                if hmac.compare_digest(base64.b64decode(value), expected):
                    return True
            except ValueError:
                continue
    return False

Operation: duplicates and ordering

• Idempotency. webhook-id identifies the event and is kept across retries and redeliveries. Record the identifiers already processed and discard repeats with a 2xx response.
• Ordering. Each resource (subject) carries an increasing sequence. Discard an event whose sequence is lower than or equal to the last one applied for that subject. Events of different resources have no order between them.
• Retries. Masnet retries any non-2xx response for up to 72 hours; the full schedule is in Webhooks.
• Secret rotation. When rotating with overlap, the previous secret stays valid for 24 hours and webhook-signature carries two v1,… signatures separated by a space. Accept the event if either one matches.

Troubleshooting

Masnet records the response code of each attempt in the delivery history. These are the effects of each receiver response: