Plus / Pro Feature

Event Webhooks

Ephos Event Webhooks allow you to deploy real-time forensic alerts and execution signal streams directly to your own infrastructure. You can listen for key lifecycle transitions, security violations, and runtime errors as they occur.

Availability: Event Webhooks are available to Plus and Pro subscription tiers. Configure your endpoint URL and subscribe to relevant events in the **Webhooks** tab inside your Ephos Identity Dashboard.

Supported Event Types

You can selectively subscribe to the following core system and runtime events:

Event Type	Trigger Condition
`execution.blocked`	An agent execution request was blocked due to an SSRF attempt, range, or domain scope policy violation.
`execution.failed`	An outbound request failed during proxy routing (e.g. gateway network timeout, decryption failure, or target server crash).
`identity.revoked`	An active Ephos Token or Master Phantom Key was manually revoked. Note: hard deletes (purges) and key rotations do not trigger this event.
`security.freeze_enabled`	The vault was locked under a security freeze manually by an administrator.
`security.freeze_disabled`	An administrator successfully unfroze the vault, restoring secret decryption and agent proxy capabilities.
`quota.threshold_reached`	The organization has exceeded its monthly proxy request allotment under the active plan.

Verification Key & Secret Rotation

When configuring webhooks, click the Create Key button to generate a secure verification secret (with the prefix whsec_). To rotate an existing key, hover over the secret input field and click the rotation icon. Ensure you update your verification listener immediately after rotation.

Payload Structure

Webhook payloads are delivered via a POST request with a JSON body. Every delivery includes standard metadata context:

{
  "id": "evt_98b50e2ddc9943efb387052637738f61",
  "event": "execution.blocked",
  "timestamp": "2026-05-22T20:00:25Z",
  "data": {
    "organizationId": "org_2df910ab38cde",
    "reason": "SSRF_VIOLATION",
    "target": "http://169.254.169.254/latest/meta-data",
    "tokenId": "et_live_58c29e10"
  }
}

Verifying Webhook Signatures

To guarantee payload integrity and verify that the notification originated from Ephos, each request includes a cryptographic signature in the header:

X-Ephos-Signature: t=1779532585,v1=a12f8e...

The signature is computed using HMAC-SHA256 with your configured Webhook Secret. The signature string is created by concatenating the timestamp t, a dot ., and the raw stringified JSON body.

Example Verification (Node.js)

Verify signatures in your HTTP receiver using the standard Web Crypto API or Node's crypto module:

import crypto from 'crypto';

function verifyEphosWebhook(payload, signatureHeader, secret) {
  // Parse header
  const parts = signatureHeader.split(',');
  const tPart = parts.find(p => p.startsWith('t='));
  const v1Part = parts.find(p => p.startsWith('v1='));
  
  if (!tPart || !v1Part) throw new Error('Invalid signature format');
  
  const timestamp = tPart.substring(2);
  const signature = v1Part.substring(3);
  
  // Construct signature payload
  const signPayload = `${timestamp}.${payload}`;
  
  // Compute HMAC
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signPayload)
    .digest('hex');
    
  // Time-constant comparison to prevent timing attacks
  const signatureBuffer = Buffer.from(signature, 'hex');
  const expectedBuffer = Buffer.from(expectedSignature, 'hex');
  
  if (signatureBuffer.length !== expectedBuffer.length) return false;
  return crypto.timingSafeEqual(signatureBuffer, expectedBuffer);
}