HMRC Fraud Prevention Headers in Practice: What We Learned Building a Web App

Any software that calls HMRC’s Making Tax Digital APIs has to send fraud prevention headers with each request: a set of Gov-Client and Gov-Vendor headers describing the user’s device, network and the software in between. They are easy to add and surprisingly easy to get subtly wrong. This guide covers what we learned while building GovBridge’s HMRC integration in HMRC’s test environment.

Why the headers exist

HMRC uses this metadata to detect and prevent fraud against taxpayers’ accounts. It is not optional good practice: it rests on the Delivery of Tax Information through Software (Ancillary Metadata) Regulations 2019 and an HMRC direction made under them. HMRC also reviews header quality when software applies for production access, so treat the headers as part of your product, not a last-minute addition.

Start with the connection method

Every request declares a Gov-Client-Connection-Method, and that choice decides which headers you must send. A browser-based product that calls HMRC from its own servers uses WEB_APP_VIA_SERVER. A desktop app calling HMRC directly, a mobile app going through a server and a batch process each have their own method and their own list. If your product has more than one route to HMRC, each route needs the method that truly describes it. In our case the method covers the browser portal; a customer’s own server calling a gateway on their behalf is a different architecture and needs to be agreed separately.

Collect client data from the real client

Headers such as Gov-Client-Screens, Gov-Client-Window-Size, Gov-Client-Timezone and Gov-Client-Browser-JS-User-Agent describe the user’s actual browser. Gather them in the browser at the time of the action and send them to your server with the request, rather than hard-coding values or reusing yesterday’s. Gov-Client-Device-ID should identify the device consistently across sessions without being derived from personal information.

Public IP addresses: know which one you mean

This is where most implementations go wrong. Gov-Client-Public-IP and Gov-Client-Public-Port are the user’s public address and source port as seen by your infrastructure. Gov-Vendor-Public-IP is the public address of your own service that the user’s device connected to: your ingress, not the address your server uses for outgoing calls. A common shortcut, asking an external “what is my IP” service from the server, returns the egress address and is simply the wrong value.

Gov-Vendor-Forwarded then describes each public hop between the client and your server. With a CDN, load balancer or managed hosting platform in front of your application, there may be several hops, and some of them may hide information such as the original source port.

Trust forwarded headers only from hops you control

Behind proxies, the client’s address arrives in forwarding headers that anyone can forge on a direct request. Configure your application to accept them only from the specific proxies in front of it, and only for the number of hops you have verified. Where your edge provider can inject the client’s address, port and timestamp, protect that path with a shared secret so a request that bypasses the edge cannot supply its own values.

If you cannot know a value, do not invent it

Some data may be genuinely unavailable in your architecture, for example the original source port behind certain managed platforms. Do not fill the gap with a proxy port, a placeholder or a guessed address. Omit the value, document why it is unavailable, and agree the approach with HMRC. Incorrect data is worse than clearly explained missing data, because it undermines the purpose of the headers.

Validate early, and keep evidence

HMRC provides a Test Fraud Prevention Headers API in the sandbox. It checks the format of the headers on a request and returns errors and warnings for each one, and it can report on the headers your recent calls to a particular API actually sent. Run it from real browsers and devices, over IPv4 and IPv6 where you can, and fix warnings as well as errors. Record the results with dates and endpoints. A clean validator result shows the format is right; it does not prove the values are accurate or guarantee production approval.

Remember the headers contain personal data

IP addresses, device identifiers and user identifiers are personal data. Send them to HMRC as required, but keep them out of general application logs, restrict who can see stored copies and set a retention period. Your privacy notice should explain that this metadata is collected and shared with HMRC.

Where GovBridge stands

GovBridge builds these headers for its browser portal’s WEB_APP_VIA_SERVER flow and deliberately omits network fields it cannot verify. Its HMRC tools run in HMRC’s test environment only; GovBridge does not have HMRC production approval. If you are planning an HMRC integration and want a second opinion on your connection method or header data, email hello@yugsolutions.co.uk.