To verify that webhook requests are genuine and haven't been tampered with, follow these steps:
Required Information
Signature Key: Available when editing your webhook on EvolutionX Admin in Developers > Webhooks
Request Headers: HTTP_EVOX_SIGNATURE and HTTP_EVOX_TIME
Request Body: The complete JSON payload
Validation Steps
1. Extract Headers
Get these headers from the incoming request:
HTTP_EVOX_SIGNATURE - The signature to verify
HTTP_EVOX_TIME - Unix timestamp when signature was created
2. Create Signature String
Concatenate: timestamp + "." + json_payload
Example:
'1690985830.{"event_id":"evt_123","event_type":"order.created",...}'
3. Generate Expected Signature
Create HMAC-SHA256 hash:
Message: The signature string from step 2
Secret Key: Your webhook signature key
Output Format: Hexadecimal string (lowercase)
4. Compare Signatures
Use a secure comparison method to check if:
received_signature === expected_signature
⚠️ Important: Use constant-time comparison to prevent timing attacks
5. Validate Timestamp (Recommended)
Check that the request timestamp is recent (e.g., within 5 minutes) to prevent replay attacks.
Response
Valid: Return HTTP 200
Invalid: Return HTTP 401 and reject the request
Example Signature Verification
Given:
Timestamp: 1690985830
Payload: {"event_id":"evt_123","data":"test"}
Signature Key: your_secret_key
Process:
Signature String: 1690985830.{"event_id":"evt_123","data":"test"}
HMAC-SHA256: hmac_sha256('1690985830.{"event_id":"evt_123","data":"test"}', 'your_secret_key')
Result: Compare with HTTP_EVOX_SIGNATURE header
Note: Always validate webhooks before processing to ensure security and data integrity.