All webhook event deliveries are signed to ensure authenticity and integrity.

Your endpoint must validate the signature before processing any event.

Verification requests (webhook.verification) are not signed.

Webhook endpoints must:

Requests are delivered only over secure connections.

Each event delivery includes the header:

X-Alvys-Signature

Format:

t={timestamp},v1={signature}

During secret regeneration, the header may include two signatures:

t={timestamp},v1={new_signature},v0={previous_signature}

Where:

The signature is generated from:

{timestamp}.{eventId}.{raw_request_body}

Important:

To validate a delivery:

Signature comparison should use constant-time comparison to prevent timing attacks.

It is recommended to reject requests where:

|current_time - timestamp| > 5 minutes

This helps reduce replay risk.

Each webhook has a unique signing secret.

The secret:

If the signature cannot be verified:

Signature validation must occur before executing any business logic.