Adding a new External Service Integration
Last Updated: August 5, 2025
The steps below explain how to add a new external service integration.
Establish connectivity
From a fwdproxy instance on a given environment, try to reach the new service via whatever endpoint you have with curl. Anything over port 443 should work, but alternate ports need an ESECC request.
Forward Proxy
Once you have verified connectivity, add entries to the forward proxy deployments in the vsp-platform-fwdproxy repo.
SSL Keys
Many backend VA services require a client SSL certificate and key for authentication. Securely generate a private key and certificate using the instructions at: Venafi: Create and download TLS certificates. (Note: Those instructions are for Platform engineers, specifically.) Add the cert as a Jinja2 template to ansible/deployment/config/fwdproxy/, and add the private key to the AWS Parameter Store with a name like /devops/certificates/<service>.key .
NOTE: Currently, we don't impose CN restrictions on the SSL certs for new External Service Integration
Security Group / ELB config
Validate that the ports assigned for the forward proxy are listed in the listener_ports variable in terraform/environments/<env>/main.tf. The port should match what is in the Forward Proxy config above.
Rails Config
Add the required host redirects in vets-api. See these docs: https://depo-platform-documentation.scrollhelp.site/developer-docs/settings-and-parameter-store.
Healthy Traffic
The forward proxy serves several critical functions on the Platform to ensure healthy traffic. First, it performs short-circuiting (leveraging health checks) to help protect external services from getting overloaded if they become unhealthy. Second, it handles mTLS connections (see the SSL keys section above) that would otherwise need to be managed by the applications, requiring each application to redeploy any time a certificate rotates.
Centralized Service Definition
Having a central location to define all external services prevents tracking each application and its external connections (a many-to-many relationship), which prevents deploying many applications in the event of an external service definition change.
Needed Information:
Forward Proxy Service Onboarding Request Template:
Requestor & Service Overview
Requesting team / product:
Service name:
Service provider / vendor (if external):
Brief description of what this service does and why vets-api needs it:Environments & URLs
For each environment (Dev, Staging, Prod), list details separately.
Environment: (Dev / Staging / Prod / Other)
Base URL(s) (e.g., https://api.example.com):
Any additional hostnames used (auth endpoints, CDNs, etc.):
Does the provider require us to be on an IP allowlist?Connectivity, Ports, and Protocols
Desired protocol: (HTTP / HTTPS / Other)
Desired port: (80 / 443 preferred — others require prior approval)
Does the service support standard TLS over 443?
Does the service require SNI? If yes, which hostname should be used for SNI?
Are there any non-standard requirements (custom ports, legacy TLS versions, specific cipher suites, etc.)?Certificates, TLS, and mTLS
Does your service require mutual TLS (client certificate from us)? (Yes/No)
If Yes:
What part of the client certificate do you validate? (CN, SAN, issuer, etc.)
Do you require a specific CA or certificate chain? Please provide details.
Any certificate pinning or fingerprint checks on your side?
Server certificate details:
Issuing CA (public CA, private CA, etc.):
Expected certificate subject / SAN hostnames:Authentication & Authorization
Authentication method (e.g., API key, OAuth2, JWT, Basic Auth, custom header):
How are credentials provided to us? (password manager, secret vault process, etc.):
Example of required auth headers / tokens (mask secrets):
Any special headers required to identify our application or environment?API Contract & Sample Requests
For each key operation we will call:
Operation name / purpose:
HTTP method (GET/POST/PUT/DELETE/etc.):
Full path (relative to base URL):
Required query parameters:
Required headers (excluding auth secrets):
Typical request body (structure / JSON schema / example, with sensitive values masked):
Typical successful response (status code, example body):
Known error responses (status codes, example bodies, and what they mean):
Sample Request (curl or HTTP)
Please provide at least one fully-formed sample request per operation, including all required headers (with dummy values).Health Check & Monitoring
Health check endpoint URL (relative to base URL):
HTTP method:
Expected status code for “healthy”:
Optional: expected response body / substring to check:
Is the health endpoint rate-limited or restricted in any way?
Any other recommended synthetic checks (e.g., lightweight read-only endpoint we can call)?Traffic Characteristics & Limits
Recommended client timeout settings:
Retry guidance (which status codes are safe to retry, backoff recommendations):Security & Data Handling
Data classification / sensitivity (e.g., PII, PHI, none):
Are there any restrictions on what data may be sent?
Required HTTP methods (list only what we must allow):
Compliance requirements (e.g., HIPAA, FedRAMP, PCI) that affect integration:
Logging expectations/restrictions (e.g., fields that must not be logged):
Help and feedback
Get help from the Platform Support Team in Slack.
Submit a feature idea to the Platform.