Start with identity and record relationships
A connector can move a record without knowing whether it represents the same entity in the destination. Define the matching rule before the first write. A source record ID paired with its source system is usually more stable than a display name. Email and company domain can be useful matching inputs, but they require explicit rules for changes and uncertain matches.
Preserve relationships as well as fields. A contact linked to the wrong company may pass a field completeness check while creating a serious operational error. The contract should identify parent and child relationships, association direction and the sequence required when related records are created.
Assign an owner to each value
An integration running in both directions still needs an authority model. For each shared field, record the system responsible for its value, whether another system may propose an update and how conflicts are resolved. A simple last update wins rule can erase a deliberate business decision with an older event delivered late.
Specify the difference between an absent value, an empty value and an intentional deletion. They are not interchangeable. The contract should also cover allowed values, type conversions, time zones and the treatment of values that the destination cannot represent. Invalid data belongs in an exception path with a reason an operator can understand.
Choose the event model deliberately
A webhook, an event journal and a scheduled extract have different operating behavior. Push delivery needs a receiving endpoint and a response policy. A journal consumer needs a durable position and a recovery strategy. A scheduled extract needs a watermark and a way to detect records that changed near the boundary of a run.
Confirm the app type, API version, permissions and delivery model before implementing HubSpot events. The webhook guide documents batched notifications, possible duplicate delivery and a lack of chronological ordering. The event payload, subscription configuration and signature validation method must match the selected app model rather than an example copied from a different interface.
Make replay safe
Networks fail after a destination may already have accepted a write. The source can therefore receive an error even though the business action succeeded. A retry must not create another opportunity, task or message. Use supported idempotency controls where available, or design a processing record and stable business key around the action.
Retries should be bounded and appropriate to the failure. Temporary throttling may justify delayed attempts, while an invalid field needs correction. Preserve enough execution context to investigate the problem without exposing unnecessary personal data in logs. A failed message should have an owner and an agreed resolution path.
Do not confuse event identity with record identity
HubSpot documents that the eventId in a webhook notification is not guaranteed unique. An integration therefore needs more context than that field alone when identifying a repeated event. Preserve the portal, subscription, object, event type, business timestamp and relevant change information, then design and test a fingerprint appropriate to the selected event model. Record identity and business action identity remain separate concerns.
For example, two legitimate updates to the same contact must not be collapsed merely because they share an object ID. Conversely, two deliveries of the same qualification change must not create two sales tasks. A processing ledger should connect the accepted event to the intended business action and the destination reference. Reconciliation provides another route to detect incorrect state when an event was missed or arrived late.
Reconcile state as well as executions
A successful API response proves that a request was accepted according to that endpoint’s behavior. It does not prove that every business relationship is correct or that the data remains aligned. Compare source and destination records using agreed identifiers, selected fields and relationship checks.
The final handover should include the data contract, architecture, credential ownership, monitoring and replay procedure. Test deletion, merging, partial failure and schema change scenarios before release. These details turn a connection into an integration that an operations team can maintain.