Webhook signature validation

The signalwire.core.security module verifies that an incoming webhook was signed by SignalWire with your Signing Key. Use it to protect custom (non-AgentBase) servers that receive SWML, SWAIG, or Compatibility callbacks.

SignalWire sends the signature in the X-SignalWire-Signature request header. The legacy X-Twilio-Signature header is accepted as an alias so callers migrating from the Compatibility SDK keep working unchanged.

If you build agents with AgentBase, you do not need these helpers — set the signing_key constructor parameter and the SDK validates the POST /, /swaig, and /post_prompt endpoints automatically. Use the standalone validators when you serve webhooks from your own framework or routes.

Validators

validate_webhook_signature

Validate a signature against the raw request body. The primary standalone validator.

validate_request

Legacy-compatible validator that accepts a raw body or pre-parsed form params.

make_webhook_validation_dependency

Build a FastAPI Depends() that enforces signature validation on a route.

Module constants

The module also exports the two recognized signature header names:

from signalwire.core.security import (
    SIGNALWIRE_SIGNATURE_HEADER,    # "x-signalwire-signature"
    TWILIO_COMPAT_SIGNATURE_HEADER, # "x-twilio-signature"
)