Webhook response

To subscribe to webhook notifications:#

1. Sign in: Navigate to https://dashboard.truevault.com.au/ and sign in with your credentials. (Use https://dashboard.sandbox.truevault.com.au/ for sandbox access)

2. User Settings: Once logged in, click on Account in the upper right corner.

3. Webhooks Tab: Within the user settings, find the "Webhooks" tab. Click on it to access settings related to webhook subscriptions.

4. Add a new Webhook subscription: In the Webhooks Tokens tab, you should find your existing webhooks keys listed. Click on Add Webhook if a you are not yet subscribed to API notifications.

Configuring a new Webhook#

1. Enter a name, e.g. Core API Notifications

2. Add your receiving URL - the location in your app we should send responses to. E.g. https://your-app.com/truevault/webhooks/receive

3. Add a secret_key. You must verify that all incoming requests conthain this key in a JWT inside the header x-webhook-secret. See the pseudo-code example below for an example workflow to validate the secret_key header. A suitable Linux command for a secure 32-byte (256-bit) token is openssl rand -hex 32 or cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1

4. Expand the Events options, and check all available boxes.

Pseudo-code example for verifying the webhook secret header#

function verifySecretHeader(secret_key, validate = true):
    headers = getRequestHeaders()

    // 1. Check header exists
    if "x-webhook-secret" not in headers:
        log("Webhook secret header missing")
        return 404

    // 2. Decode and validate JWT payload (expiry, timestamps, etc.)
    jws = JWT.deserialize(headers["x-webhook-secret"])
    payload = JWT.getPayload(jws)

    try:
        JWT.validatePayload(payload, require_expiry = true)
    catch InvalidPayload:
        log("Invalid webhook JWT payload")
        return 404

    // 3. Verify HMAC-SHA256 signature against shared secret
    valid = JWT.verifySignature(jws, secret_key, algorithm = HS256)

    if not valid and validate:
        log("Webhook signature verification failed")
        return 404 

Webhook request headers#

TrueVault sends these headers with every callback. Verify X-Webhook-Signature before trusting the payload.

Webhook request body#