All Docs
FeaturesMaking Tax DigitalUpdated February 27, 2026

Ensuring Gov-Vendor-Public-IP Is Always Present in HMRC Submissions

Ensuring Gov-Vendor-Public-IP Is Always Present in HMRC Submissions

Release: v1.0.227 · Severity: Medium · Area: HMRC Fraud Prevention Headers

Background

HMRC's Making Tax Digital (MTD) API requires all requests to include a set of fraud prevention headers. These headers allow HMRC to identify and validate the origin of each API call. One of the mandatory headers for applications using the WEB_APP_VIA_SERVER connection method is:

Gov-Vendor-Public-IP: <your-server-public-ip>

If this header is absent or empty, HMRC will reject the request with:

HTTP 403 INVALID_FRAUD_PREVENTION_HEADERS

This means quarterly submissions, obligation updates, and any other HMRC API interactions will fail silently at the network boundary — not during local development, but in production where the stakes are highest.

What We Found

A routine depth audit of src/lib/hmrc/fraud-prevention-headers.ts revealed that line 101 was reading the VENDOR_PUBLIC_IP environment variable but falling back to an empty string when the variable was not set:

// Before — unsafe fallback
const vendorPublicIp = process.env.VENDOR_PUBLIC_IP ?? '';

An empty string caused the header to be either omitted or sent with no value — both of which violate HMRC's fraud prevention spec.

What Changed

The fallback has been replaced with explicit enforcement. If VENDOR_PUBLIC_IP is not configured, the application now raises an error at startup or request time rather than proceeding silently with a non-compliant header set.

// After — enforced
const vendorPublicIp = process.env.VENDOR_PUBLIC_IP;
if (!vendorPublicIp) {
  throw new Error(
    'VENDOR_PUBLIC_IP environment variable is required for HMRC fraud prevention headers (Gov-Vendor-Public-IP).'
  );
}

This ensures misconfiguration is caught early and clearly, rather than resulting in mysterious 403 errors from HMRC.

What You Need To Do

If you are self-hosting or managing your own deployment, ensure the following environment variable is set in all environments that make calls to the HMRC MTD API:

VariableDescriptionExample
VENDOR_PUBLIC_IPThe public IPv4 or IPv6 address of your server as seen by HMRC203.0.113.42

How to find your server's public IP

On most Linux/cloud servers:

curl -s https://api.ipify.org

Or via your cloud provider's metadata service (e.g. AWS EC2 Instance Metadata, GCP VM metadata).

Setting the variable

.env (local / staging)

VENDOR_PUBLIC_IP=203.0.113.42

Docker / Kubernetes

env:
  - name: VENDOR_PUBLIC_IP
    value: "203.0.113.42"

⚠️ Note: If your server uses a dynamic public IP (e.g. behind NAT or a floating IP), you should ensure this value is updated whenever the IP changes, or use a fixed Elastic/Static IP in your hosting configuration.

HMRC Fraud Prevention Header Reference

The Gov-Vendor-Public-IP header is one of several required fraud prevention headers for the WEB_APP_VIA_SERVER connection method. The full set of required headers is documented in the HMRC fraud prevention specification.

Other headers managed by fraud-prevention-headers.ts include:

  • Gov-Client-Connection-Method
  • Gov-Vendor-Version
  • Gov-Client-User-IDs
  • Gov-Client-Timezone
  • Gov-Client-Local-IPs
  • Gov-Vendor-Public-IP ← this release

Ensure all required headers are correctly populated before making MTD submissions in production.

Further Reading