Webhook Integration Documentation

1: Overview

How It Works

1. Our system sends a POST request with event data to your designated HTTPS endpoint.
2. You validate the request, process the data, and return a response (e.g., 200 OK or an error-code).
3. The integration relies on secure communication and validation to ensure data integrity.

What You Need to Do

• Implement a secure HTTPS endpoint to receive JSON payloads.
• Validate incoming requests using HMAC signatures.
• Implement replay protection using timestamps (optional but recommended).
• Return appropriate HTTP status codes and responses.
• Store the shared secret we provide securely.

What We Provide

• A test environment for validating the integration and JSON payload overview.
• A shared secret for HMAC validation
• Integration support.

2: Request Details

Endpoint

Provide a secure HTTPS endpoint to receive event data.

Request Headers

 

Request Body

The request body contains event metadata and data specific to the event.

Example:
{
  "eventId": "123e4567-e89b-12d3-a456-426614174000",
  "eventType": "SSOEvent",
  "eventTimestamp": "2025-05-13T14:30:00Z",
  "data": "string"
}

3: Response Details

Success Response

Return a 200 OK status. If the event requires a response body, you'll find the details in the event documentation.
Otherwise, a simple 200 OK is sufficient.

Example:
{
  "status": "success"
}

Error Response

For invalid requests, return an appropriate HTTP status code (e.g., 400 Bad Request) with an error message.

 

Example:
{
  "error": "Invalid signature"
}

4: Security Considerations

4.1. HMAC Signature

We include an HMAC signature in the `X-Vinst-Signature` header, generated using a shared secret the timestamp in the header and the request payload.

Validation Steps:

1. Retrieve the shared secret provided during integration.
2. Compute the HMAC signature using SHA-256 and the concatenated timestamp + payload.
3. Compare the computed signature with the `X-Vinst-Signature` header value.

Pseudo-code Example:

FUNCTION ValidateHmacSignature(timestamp, payload, signature, sharedSecret):
    // Combine payload and timestamp
    dataToHash = CONCATENATE(timestamp, payload)
    // Create HMAC using the shared secret
    hmac = HMAC_SHA256(sharedSecret)
    // Compute the hash
    computedHash = hmac.COMPUTE_HASH(dataToHash)
    // Convert to Base64
    computedSignature = BASE64_ENCODE(computedHash)
    // Compare signatures
    RETURN computedSignature == signature
END FUNCTION

4.2. Timestamp for Replay Protection

To prevent replay attacks, validate the `X-Vinst-Timestamp` header to ensure it’s within a 5-minute window.

Validation Steps:
1. Parse the `Vinst-Timestamp` header (Unix format).
2. Ensure the timestamp is within 5 minutes of the current time.

Pseudo-code Example:

FUNCTION ValidateTimestamp(vinstTimestamp):
    // Convert Unix timestamp to DateTime
    requestTime = CONVERT_UNIX_TO_DATETIME(vinstTimestamp)
    // Get current UTC time
    currentTime = GET_CURRENT_UTC_TIME()
    // Calculate time difference in minutes
    timeDifference = ABS(currentTime - requestTime)
    // Check if within 5 minutes
    RETURN timeDifference <= 5
END FUNCTION

4.3. HTTPS

Your endpoint must use HTTPS to ensure data encryption. 

5: Error Handling

Invalid Request

Return an appropriate HTTP status code and error message for invalid requests (e.g., missing fields, invalid signature).

Example:
{
  "error": "Missing required field"
}

Replay Attack

If the timestamp is outside the 5-minute window, reject the request with a 403 Forbidden status.

Example:
{
  "error": "Request timestamp is too old"
}

6: Testing and Validation

Test Environment

Provide a test endpoint that mimics the production environment for validation without affecting live data.

Validation Checklist

• Verify `X-Vinst-Signature` validation.
• Verify JSON payload data
• Ensure appropriate HTTP status codes and responses.
• Confirm `X-Vinst-Timestamp` is within 5 minutes (if implemented).

7. Contact Information

For assistance, contact our support team at va@visma.com.