Webhook Events

Overview

Webhooks enable event-driven architectures by pushing data to your servers instead of polling the API. When an event triggers, Env sends an HTTP POST request to your configured endpoint with a JSON payload and security headers.

⚡ Implementation Note

Always respond with a 2xx status code within 5 seconds. Env processes webhooks asynchronously and does not block on your response, but timeouts will trigger retries.

Event Catalog

Filter and subscribe to specific event types via the Dashboard or /v1/webhooks/subscriptions endpoint.

sustainability.carbon_reduced

Triggered when verified organizational carbon emissions drop ≥5% month-over-month, or when a major offset/abatement initiative reaches a milestone.

🌱 Sustainability 📉 Metrics Verified

compliance.report_ready

Fired when an automated ESG/regulatory report (GRI, SASB, TCFD, CSRD, SEC) finishes compilation and is ready for export or stakeholder distribution.

📋 Compliance 📄 Reporting Auto-generated

supplychain.audit_complete

Sent when a third-party supplier sustainability audit finishes processing. Includes risk scores, scope 3 allocations, and recommended remediation steps.

🔗 Supply Chain 🔍 Audits External

system.integration_sync_failed

Triggered when Env encounters persistent errors syncing data from connected sources (ERP, IoT telemetry, utility APIs, or accounting systems).

⚙️ System 🔌 Integrations Critical

Payload Structure

Every webhook uses a consistent envelope. The data object contains event-specific fields and schemas.

JSON

{
  "id": "evt_9x2k7m4p0q1r5s8t",
  "type": "sustainability.carbon_reduced",
  "created_at": "2025-11-12T14:32:00Z",
  "data": {
    "organization_id": "org_env_8821",
    "workspace": "global-operations",
    "metrics": {
      "current_tonnes_co2": 142.5,
      "previous_tonnes_co2": 168.2,
      "reduction_percentage": 15.3,
      "period": "2025-Q3",
      "scope": ["scope_1", "scope_2"]
    },
    "verification": {
      "method": "third_party_audit",
      "auditor": "EcoVerify Global",
      "status": "certified"
    }
  }
}

Standard Fields

Field	Type	Description
`id`	string	UUIDv4 event identifier
`type`	string	Event category and action
`created_at`	ISO 8601	UTC timestamp of generation
`data`	object	Domain-specific payload

Security & Signatures

Env signs every webhook using HMAC-SHA256. Verify the signature to prevent spoofing and ensure data integrity.

Headers

Header	Description
`x-env-signature`	HMAC-SHA256 hex digest of `payload.timestamp`
`x-env-timestamp`	Unix epoch timestamp of request
`x-env-idempotency-key`	Unique key to safely deduplicate retries
`x-env-version`	API schema version (e.g., `v2025.10`)

Verification Example

JavaScript (Node.js)

const crypto = require('crypto');

function verifyWebhook(rawBody, headers, secret) {
  const timestamp = headers['x-env-timestamp'];
  const signature = headers['x-env-signature'];
  const payload = rawBody + '.' + timestamp;
  
  const hmac = crypto.createHmac('sha256', secret);
  const expected = hmac.update(payload).digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

Delivery & Retries

Env guarantees at-least-once delivery with exponential backoff. If your endpoint returns a non-2xx status or times out after 5 seconds, we retry up to 5 times:

Attempt 1: Immediate
Attempt 2: 60 seconds
Attempt 3: 5 minutes
Attempt 4: 15 minutes
Attempt 5: 1 hour
Attempt 6: 4 hours

After final failure, events are marked status: "failed" in the dashboard. Use the POST /v1/webhooks/replay endpoint or click "Replay" in the UI to reprocess failed events.

Testing & Debugging

Trigger test events without affecting production data. Test payloads are prefixed with test_ in the id field.

Bash

env-cli webhooks test \
  --event-type sustainability.carbon_reduced \
  --endpoint https://api.yourapp.com/webhooks/env \
  --workspace global-operations

Monitor delivery logs, inspect payloads, and manage subscriptions directly from Dashboard → Settings → Webhooks.

Webhook Events Reference