Core

Webhook signature validation

View as MarkdownOpen in Claude

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:

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