Webhooks

Receive real-time HTTP notifications when specific events occur in your Env organization. Configure endpoints, verify signatures, and handle payloads with confidence.

How Webhooks Work

When a supported event occurs, Env sends an HTTP POST request to your configured endpoint URL. The request contains a JSON payload with event details and metadata. If your server responds with a 2xx status code within 30 seconds, Env marks the webhook as delivered. Otherwise, it triggers our automatic retry mechanism.

Note: All webhook requests originate from hooks.env.io. We recommend whitelisting this domain in your firewall rules.

Supported Events

Event Description Category
carbon.report_generated A new carbon footprint report has been finalized Sustainability
energy.alert_triggered Energy consumption exceeded configured threshold Monitoring
compliance.audit_passed Organization successfully completed a compliance audit Compliance
supply_chain.update Supplier sustainability score or tier changed Supply Chain

Request Payload Structure

Every webhook payload follows a consistent envelope format:

{
  "id": "evt_8f7d6c5b4a3e2f1d",
  "type": "carbon.report_generated",
  "timestamp": "2025-03-15T14:32:00Z",
  "data": {
    "report_id": "rpt_9a8b7c6d5e4f",
    "period": "2025-Q1",
    "total_co2e_tonnes": 142.8,
    "status": "finalized"
  },
  "metadata": {
    "org_id": "org_env_12345",
    "api_version": "2025-01-15"
  }
}

Security & Signature Verification

All webhook requests include an X-Env-Signature header containing an HMAC-SHA256 hex digest. Verify this signature to ensure the payload originated from Env.

Verification Example (Node.js)

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(digest));
}

// Usage in Express:
app.post('/webhooks/env', (req, res) => {
  const sig = req.headers['x-env-signature'];
  const valid = verifySignature(req.body, sig, process.env.WEBHOOK_SECRET);
  
  if (!valid) return res.status(401).send('Invalid signature');
  
  handleEvent(req.body);
  res.status(200).send('OK');
});

Configure Your Endpoint

Add and manage webhook URLs for your organization below. You can subscribe to multiple events per endpoint.

Retry Logic & Reliability

If your endpoint fails to respond with a 2xx status or times out after 30 seconds, Env will automatically retry delivery using exponential backoff:

  1. Attempt 1: Immediate retry after 5 seconds
  2. Attempt 2: 30 seconds
  3. Attempt 3: 2 minutes
  4. Attempt 4: 10 minutes
  5. Attempt 5: 1 hour (final attempt)

Failed webhooks are retained for 7 days and can be manually replayed from the dashboard. All delivery attempts are logged with response codes and latency metrics.

Troubleshooting

  • 403 Forbidden: Check your server firewall and ensure the request IP is whitelisted.
  • Signature Mismatch: Verify you're using the exact raw request body (not parsed JSON) for HMAC calculation.
  • Timeout Errors: Process webhooks asynchronously. Return 200 OK immediately and queue the payload for background processing.