Skip to navigation

Webhook Signature Validation

View as MarkdownOpen in Claude

SignalWire signs the webhook requests it sends to your endpoints. These utilities verify those signatures so you can reject forged or tampered requests. All are imported directly from @signalwire/sdk.

SignalWire sends two signature headers on signed webhooks: X-SignalWire-Sha256-Signature (HMAC-SHA256) and X-SignalWire-Signature (SHA-1). validate() and webhookValidationMiddleware() check the SHA-256 header first and fall back to the SHA-1 header when the SHA-256 header is missing or doesn’t match, so cXML webhooks and deployments that only receive the SHA-1 header keep validating.

import {
validateWebhookSignature,
validateWebhookSignatureSha256,
validateRequest,
validate,
webhookValidationMiddleware,
SIGNALWIRE_SIGNATURE_HEADER,
SIGNALWIRE_SHA256_SIGNATURE_HEADER,
TWILIO_COMPAT_SIGNATURE_HEADER,
} from '@signalwire/sdk';

If you are building with AgentBase, set the signingKey constructor option instead — the agent auto-mounts webhookValidationMiddleware on its endpoints for you.

Functions

Signature header constants

SIGNALWIRE_SIGNATURE_HEADER
string

The SignalWire signature header name: 'x-signalwire-signature'.

SIGNALWIRE_SHA256_SIGNATURE_HEADER
string

The SHA-256 signature header name: 'x-signalwire-sha256-signature'. When a request carries it, validate() and the middleware check it before the SHA-1 header.

TWILIO_COMPAT_SIGNATURE_HEADER
string

The legacy signature header name, 'x-twilio-signature'. The validators accept it as an alias of SIGNALWIRE_SIGNATURE_HEADER.