Conversions API Hashing: Normalising Customer Parameters Before SHA-256 and Which Fields Stay Unhashed
Contents
A Conversions API event that carries a hashed email address looks the same whether the hashing was done right or wrong. The payload validates, the API answers with a success, the event counter goes up, and the match quality figure stays where it was – because the address, correctly hashed into a string that corresponds to nothing, was compared against a customer base and found in none of it.
That is the failure mode worth understanding before any of the plumbing: hashing does not fail loudly, it fails by producing something that is technically flawless and semantically empty.
Why a Small Difference Is a Total Difference
A hash function is built so that a minimal change to the input produces an unrecognisably different output. That property is what makes hashing useful, and it is exactly what makes a normalisation mistake fatal: there is no such thing as almost matching. Two hashes are identical or they have nothing to do with each other, and no amount of fuzzy matching downstream can recover the difference.
So the entire question of whether an event finds a person is decided before the hash function is ever called, in the few lines that decide what exactly goes into it.
The Form Each Parameter Has to Take
| Parameter | Required form | What goes wrong |
|---|---|---|
em |
trimmed, lowercase | a capital from the form, a trailing space from a paste |
ph |
digits only, with country code | the national trunk zero in +49 (0)170 survives |
fn, ln |
lowercase, no punctuation or spaces | a hyphen in a double-barrelled surname |
ct |
lowercase, no spaces | Frankfurt am Main keeps its spaces |
st, country |
two-letter lowercase code | the country is written out |
ge |
exactly f or m |
anything else, hashed as if it were a value |
db |
YYYYMMDD | a locale date format, silently reordered |
The phone number deserves a note of its own, because it is the one case that cannot be normalised mechanically. Stripping non-digits from +49 (0)170 1234567 leaves 4901701234567, and the zero after the country code is a national dialling prefix that has no place in an international number. No rule can decide that reliably for every country, which is why the honest handling is to strip, then flag the suspicious pattern for a human rather than guess.
The Parameters That Must Not Be Hashed
The opposite mistake is rarer and just as final. client_ip_address, client_user_agent, fbp and fbc are sent in plain text. They are not personal identifiers in the sense the hashed fields are; they are values Meta matches against its own records, and a hashed one is a string that corresponds to nothing on the other side.
This happens most often when a hashing helper is applied to the whole user-data object at once, which is a reasonable-looking piece of code and wrong in exactly four fields. A helper that hashes by field name rather than by object is the version that survives a schema change.
What This Looks Like From Outside
# the same address, three ways
" Max.Mustermann@Example.COM " → 524d6368ceb086b2b1d8fed14ee75313…
" max.mustermann@example.com " → de4c5edc5348280eedb5b029d7851764…
"max.mustermann@example.com" → dd432348e6c3373c5f646913fa94ae79…
# only the third is ever compared against anythingNone of these produces an error. The event count in the events manager is identical in all three cases, the delivery is confirmed in all three cases, and the only figure that moves is the match quality – downwards, slowly, in a way that is easy to attribute to seasonality or to a consent change.
Which is why the useful check is not the API response but a comparison against a known value. Take one address from the customer base, hash it the way the shop hashes it, hash it the way the specification prescribes, and compare the two strings. They match or the pipeline has a normalisation bug, and the answer takes a minute.
Where the Normalisation Belongs
The last decision is architectural. Normalisation can happen in the browser, in the server container, or in the backend that has the customer record – and only the last of those has the original value in the form the customer base stores it in.
Doing it in the server-side container is the common middle ground and works, provided the container receives the raw value and not something a form has already mangled. Doing it in the browser is the one arrangement to avoid: it puts the plain address into a request that leaves the visitor’s machine, which is precisely what the hashing was there to prevent.
Sources
Related articles
