Non-functional requirements

When developing a client application that communicates with Customer Engagement using your tenant-specific API key, it’s essential to follow certain non-functional requirements (NFRs). The guidelines listed here ensure that your integration is secure and resilient and aligns with Voyado’s best practices.

​

Security best practices

​

Use HTTPS with TLS 1.2 or higher for encryption in transit

All API requests must be made over HTTPS to protect data, including the API key, in transit. TLS ensures that credentials and payloads cannot be intercepted or tampered with during transmission.

​

Store the API key securely at rest

If your client needs to persist the API key:

• Store it in a secure secrets management system (e.g., AWS Secrets Manager, Azure Key Vault).
• Avoid hardcoding the key in source code, config files, or environment variables exposed to user-facing environments.
• Use file system-level encryption and proper access controls if stored locally.
• Never store the API key in frontend or browser-accessible code — all calls to the Voyado API must be made from trusted backend systems.

​

Prevent exposure in logs or error messages

Do not log the API key or include it in exception traces. Redact sensitive headers before logging outbound requests.

​

Use the correct header-based authentication

Send the API key in the apikey HTTP header, not in the URL or query string, to avoid accidental exposure via browser history or intermediaries.

​

Implement IP Filtering

Consider restricting API access for your tenant to specific IP addresses using Voyado’s IP filtering feature. This adds an extra layer of security by ensuring that only requests from authorized IPs are accepted.

​

Testing and environment readiness

​

Use the staging Environment

Before deploying to production, thoroughly test your integration in Voyado’s staging environment. Doing this allows you to:

• Validate authentication and API connectivity.
• Test all intended API endpoints, including handling of success and error responses.
• Simulate various scenarios, such as network latency and API timeouts.
• Ensure proper logging and monitoring are in place.

​

Resilience and Error Handling

​

Implement appropriate retry logic

Your client should be able to handle temporary issues gracefully without overwhelming the API or duplicating requests unnecessarily. Retries should be performed only under the following conditions:

• When server timeout (504) is received: This happens when processing the request taked too long. The timeout threshold is different for each endpoint, and is generally shorter for customer facing experiences.
• In the case of other 5xx server errors: These indicate temporary issues on the Voyado side. It is safe to retry with exponential back-off.
• Connection timeouts or network interruptions: These are transient connectivity issues can occur between your client and Voyado’s API.
• There is a 408 (Request Timeout): The server didn’t get the full request in time, often due to network delays. it is safe to retry with back-off, especially for idempotent requests.
• In the case of 429 (Too Many Requests): The client is being rate-limited. Retry after a short delay using exponential back-off.

Do not retry under these conditions:

• There is a 4xx client error that is not 408 or 429: Errors such 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), or 404 (Not Found) indicate a problem with the request itself and will not succeed on retry without changes being made.
• There are invalid payloads or schema violations: Fix the validation issues before retrying the same request.
• There are duplicate-sensitive POST operations: Instead of blindly retrying, confirm whether the initial request succeeded (such as by using a GET) to avoid duplicating actions.

​

Recommended strategy

• Use exponential back-off with added jitter (random delay variation).
• Cap the retries after a reasonable limit (such as 3–5 attempts).
• Always log retry attempts, including reasons and delays.

​

Monitoring and Logging

​

Comprehensive Logging

Maintain detailed logs of all API interactions, including:

• Request and response timestamps.
• Endpoint URLs and HTTP methods.
• Status codes and error messages.

This facilitates troubleshooting and performance monitoring.

​

Monitor Performance Metrics

Regularly track metrics such as:

• API response times.
• Error rates.
• Request volumes.

Monitoring these metrics helps in identifying and addressing performance bottlenecks promptly.

​

Input Validation and Data Integrity

​

Validate and Sanitize Inputs

Ensure that all data sent to the API is properly validated and sanitized. This prevents malformed requests and potential security vulnerabilities. 

​

Secure Data Storage

If your application stores data retrieved from the API, implement appropriate security measures to protect this data, especially if it includes personal or sensitive information.

​

NFRs for webhooks

If your system subscribes to webhooks from Voyado Customer Engagement, your webhook listener must be designed for security, reliability, and scalability.

​

Validate the source of incoming webhook requests

Each webhook request includes an HMAC-SHA256 signature in the x-voyado-signature header, based on a shared secret. Your listener should compute the expected signature and compare it to the one received to verify that the payload genuinely comes from Voyado. This protects against spoofed or unauthorized requests.

​

Use HTTPS and restrict access to the webhook endpoint

Only expose your listener over HTTPS to ensure data is encrypted in transit. Restrict access to your webhook endpoint by allowing only traffic from Svix’s external delivery IPs — the service Voyado uses to send webhooks. While not required, this is strongly recommended to reduce the risk of unauthorized access.

​

Support payload encryption if required

If sensitive data is to be included in some webhook payload, you can configure your webhooks to use AES-256 encryption. Your system must then decrypt the payload on receipt using your private key.

​

Respond quickly and asynchronously

Webhook endpoints should return a 200 OK response as soon as possible to acknowledge receipt. Any heavy processing (e.g., database updates or downstream API calls) should be handled asynchronously. This ensures reliable delivery and prevents timeouts.

​

Implement rate limiting and queuing if needed

If multiple events are sent in a short time (e.g., during peak campaigns), your listener should throttle incoming traffic and queue processing to avoid failures or overload.

​

Log and monitor webhook activity

Log incoming webhook events and responses, including timestamps, event types, and delivery status. Monitor for spikes, failures, or validation errors to ensure system health.