Security

Signature verification (Ed25519)

Webhook authenticity and integrity are ensured using Ed25519 asymmetric signatures.

Key material from TechWolf

For each webhook endpoint, TechWolf provides:

Public key (Ed25519) - used by you to verify webhook signatures

Private keys are held only by TechWolf and securely managed.

Signed message format

The signature is computed over:

timestamp:tenant:event_id:request_body

The result is sent in the X-Signature-V1 header:

X-Signature-V1: <hex-signature-1>,<hex-signature-2>

TechWolf supports non-breaking key rotation. During a rotation window, the same request may be signed with multiple active private keys, so X-Signature-V1 can contain several signatures. Validate the webhook by verifying that at least one signature matches using any of the currently active public keys. This allows key updates without downtime.

Security responsibilities

You must:

Verify the Ed25519 signature using the provided public key
Validate timestamp freshness to prevent replay attacks (e.g. reject requests where the X-Signature-Timestamp is older than 5 minutes)
Reject invalid or stale requests with a 401 response

Python example: signature verification

from nacl.signing import VerifyKey
from nacl.exceptions import BadSignatureError

# Public key provided by TechWolf (hex-encoded)
PUBLIC_KEY = "TECHWOLF_PUBLIC_KEY_HEX"

verify_key = VerifyKey(bytes.fromhex(PUBLIC_KEY))

signatures = request.headers["X-Signature-V1"]
timestamp = request.headers["X-Signature-Timestamp"]
tenant = request.headers["X-Tenant"]
event_id = request.headers["X-Event-Id"]
body = request.data.decode("utf-8")

# TechWolf signature payload format:
# <timestamp>:<tenant>:<event_id>:<request_body>
message = f"{timestamp}:{tenant}:{event_id}:{body}".encode("utf-8")

# X-Signature-V1 may contain multiple comma-separated signatures.
# The request is valid if at least one signature matches.
for signature in signatures.split(","):
    try:
        verify_key.verify(
            message,
            bytes.fromhex(signature.strip()),
        )
        break
    except BadSignatureError:
        continue
else:
    abort(401, "invalid request signature")

OAuth2 endpoint authentication (optional)

In addition to signature verification, TechWolf can authenticate webhook requests to your endpoint using OAuth2. This protects against unauthorised callers reaching your endpoint. OAuth2 is optional and does not replace signature verification; authenticity and integrity are always guaranteed by Ed25519.

Request format

When OAuth2 is enabled, TechWolf sends an access token in the Authorization header:

Authorization: Bearer <access_token>

Enabling OAuth2

To enable OAuth2 for webhook delivery, you must provide:

Item	Description
OAuth2 Token URL	Your token endpoint
Grant type	`client_credentials`
Client credentials for TechWolf	`client_id`, `client_secret`
Scope	As required by your endpoint
Additional parameters	Any other fields your token endpoint expects (e.g. `audience`, `resource`, or custom parameters). Provide name and value per parameter.

Client authentication method

When TechWolf requests an access token from your token endpoint (client credentials grant), the client_id and client_secret can be sent in one of two ways:

Method	Description
Form-encoded (POST)	`client_id` and `client_secret` in the POST body (`application/x-www-form-urlencoded`).
HTTP Basic (POST)	`client_id` and `client_secret` in the `Authorization` header (Basic auth).

Custom headers (optional)

You can configure custom headers that TechWolf will send with every webhook request to your endpoint (e.g. for routing or internal auth). The standard headers (including signature headers) are always sent; custom headers are added on top.

Integrations

Datasource Integrations

Employee Skill Assistant

TechWolf Analyst Agent

Skill Sync Integrations

Reporting

Webhooks

References

Signature verification (Ed25519)

Key material from TechWolf

Signed message format

Security responsibilities

Python example: signature verification

OAuth2 endpoint authentication (optional)

Request format

Enabling OAuth2

Client authentication method

Custom headers (optional)

​Signature verification (Ed25519)

​Key material from TechWolf

​Signed message format

​Security responsibilities

​Python example: signature verification

​OAuth2 endpoint authentication (optional)

​Request format

​Enabling OAuth2

​Client authentication method

​Custom headers (optional)

Signature verification (Ed25519)

Key material from TechWolf

Signed message format

Security responsibilities

Python example: signature verification

OAuth2 endpoint authentication (optional)

Request format

Enabling OAuth2

Client authentication method

Custom headers (optional)