Verify webhook signatures

When you configure a signing secret for your webhook, TheirStack signs every delivery with an HMAC-SHA256 signature so you can verify the payload was sent by TheirStack and has not been tampered with.

How it works

1. You set a signing secret (minimum 16 characters) when creating or editing a webhook.
2. For every delivery, TheirStack computes an HMAC hex digest of the raw JSON body using your secret and includes it in the X-TheirStack-Signature-256 header:

X-TheirStack-Signature-256: sha256=<hex_digest>

3. Your endpoint recomputes the same HMAC and compares the two values using a timing-safe comparison to prevent timing attacks.

Setting up a signing secret

You can add a signing secret when creating a new webhook or update an existing one:

• In the app — use the "Signing Secret" field in the webhook creation/edit form. You can generate a random secret or provide your own (minimum 16 characters).
• Via the API — include a secret field in the request body when calling POST /v0/webhooks or PATCH /v0/webhooks/{id}.

Validating deliveries

import hashlib
import hmac
import os

from flask import Flask, request, abort

WEBHOOK_SECRET = os.environ["THEIRSTACK_WEBHOOK_SECRET"]

def verify_signature(payload: bytes, secret: str, signature_header: str) -> bool:
    """Verify the X-TheirStack-Signature-256 header."""
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

app = Flask(__name__)

@app.route("/webhook", methods=["POST"])
def webhook():
    signature = request.headers.get("X-TheirStack-Signature-256", "")
    if not verify_signature(request.data, WEBHOOK_SECRET, signature):
        abort(403)
    event = request.json
    # Process the event
    return "", 200

Testing your implementation

You can verify your implementation with these test values:

Troubleshooting

• Signature mismatch — Make sure you are comparing against the raw request body (bytes), not a parsed/re-serialized JSON object. Re-serialization can change key order or whitespace.
• Missing header — The X-TheirStack-Signature-256 header is only included when a signing secret is configured for the webhook.
• Encoding issues — The payload may contain unicode characters. Always handle it as UTF-8.