Webhook customer identifiers should remain stable when names, email addresses, or telephone numbers change. Use explicit source namespaces and trusted mappings so an event cannot accidentally update the wrong customer.
Stable identifiers describe entities, not contact details
A stable external identifier represents a customer within the source system’s documented scope. It may be unique only within an account or tenant, so the full mapping key often needs source system, source account, and entity identifier.
For a proposed payload contract, include an event identifier, event type, source entity reference, relevant version, and only the required business fields. Resolve the local customer through an authorised mapping rather than treating a supplied local database identifier as trusted.
Contact values can support an approved reconciliation process, but they are poor universal keys. Shared numbers, changed emails, merged accounts, and reused addresses make naive matching unreliable.
Test a fictional email change
Customer C-18 changes their email address in the source system. The webhook keeps C-18 as the entity reference and supplies the new email as data. The receiver updates the mapped customer rather than creating a second person because the old matching value disappeared.
Now send customer C-18 from a different source account. If the receiver ignores the account namespace, it may overwrite the first account’s record. The trusted integration account and mapping must keep those identities separate.
| Payload condition | Expected result |
|---|---|
| Contact value changes | Existing mapped customer remains linked |
| Same entity ID in another account | Separate namespace enforced |
| Unknown customer reference | Reconciliation or controlled creation policy |
| Merged source customer | Explicit supported mapping transition |
| Caller-supplied local ID | No bypass of trusted account scope |
Replay these fixtures and inspect both the target record and untouched neighbouring records. A correct-looking update can hide a cross-account mutation if the test checks only returned text.
Plan mapping lifecycle explicitly
Customers may merge, split, or be deleted. Record mapping changes with an owner and evidence, and define how late events referencing retired entities are handled. Do not silently reuse an old external key for a different person.
Durable mappings increase maintenance and storage but reduce ambiguous matching. Keep personal contact details out of routine mapping logs where an opaque reference is sufficient. Unknown mapping should be a visible operational state, not a reason to guess.
This payload design is proposed. The StackFlight case study describes a full-stack product with private account data; it does not claim this webhook mapping implementation. Read cross-provider event deduplication.
Customer identifier FAQ
Can email be the primary customer identifier?
Use the source’s stable entity key where available. Email changes and shared addresses complicate identity.
Is a globally unique event ID also a customer key?
No. Event identity and customer identity describe different objects.
What happens when a mapping is missing?
Follow a defined authorised creation or reconciliation process and preserve the unresolved event without altering a guessed customer.