Webhook configuration

Overview

Envtracker exposes webhook endpoints so you can automate deployment notifications, environment creation, and application assignment from CI/CD pipelines or external systems.

All webhook requests are authenticated using:

• A webhook key (Key ID + Secret)
• An HMAC-SHA256 signature

Creating a webhook key

Before making any requests, you need to generate a webhook key from your tenant dashboard:

1. Navigate to Settings → Configuration → Webhook Keys
2. Click Create Webhook Key
3. Copy and securely store the Key ID and Secret

The secret is shown only once and cannot be retrieved later.

Treat your webhook secret like a password. Never commit it to source control. Use environment variables or a secrets manager.

Authentication headers

Every request to a webhook endpoint must include these headers:

Header	Description
X-Webhook-Key-Id	Your webhook key ID
X-Webhook-Timestamp	Current Unix timestamp in seconds
X-Webhook-Signature	HMAC-SHA256 signature

Signature calculation

The signature is computed by concatenating the timestamp and the raw JSON body, then signing with your secret using HMAC-SHA256.

signature = HMAC-SHA256(secret, "{timestamp}.{rawBody}")

Node.js example

const timestamp = Math.floor(Date.now() / 1000);
const rawPayload = `${timestamp}.${JSON.stringify(payload)}`;
const signature = crypto.createHmac('sha256', webhookSecret).update(rawPayload).digest('hex');

Bash / cURL example

TIMESTAMP=$(date +%s)
SIGNATURE=$(echo -n "${TIMESTAMP}.${PAYLOAD}" | openssl dgst -sha256 -hmac "${WEBHOOK_SECRET}" | sed 's/^.* //')

Signature validation rules

• The timestamp must be within 5 minutes (300 seconds) of the server time
• Signatures are verified using a timing-safe comparison

Base URL

All endpoints use your tenant subdomain:

https://<your-tenant>.envtracker.io

Common authentication errors

HTTP Status	Reason
401 missing_headers	One or more required headers is missing
401 missing_key	No webhook key found matching the provided Key ID
401 timeout	Timestamp is more than 5 minutes away from server time
401 invalid_signature	Signature does not match