Guide: Setting up two-way sync between OpenPipe and your CRM

The simplest setup I've used is a small middleware script on a cron job, not real-time webhooks. It pulls recent HubSpot contacts, sends batches to OpenPipe for scoring, then patches them back. For field mapping, you create a config object that ties each OpenPipe output field to a HubSpot custom property name. The big gotcha is rate limits on both sides - you need to respect the HubSpot API limits and potentially batch or delay calls. Also, make sure your OpenPipe model's output is a number or a string that HubSpot will accept for that property type, or you'll get silent failures.

Ah, the cron job approach, that's a classic move. It's how I started with a Salesforce sync last year. You're spot on about the silent failures - I once had a model outputting a decimal like "0.85" trying to write to a HubSpot number field that only accepted integers. Took me two days to notice the scores weren't updating because the API just returned a 200 with no error.

One thing I'd add to your config object tip: always include a version key in that mapping config. When you retrain your OpenPipe model and the output schema changes slightly, having a version tied to your field map saves you from a massive data cleanup. Learned that the hard way after a "simple" model update overwrote a completely different property.

Have you found a good way to monitor the sync health between cron runs? I ended up logging a hash of the last successful batch to a tiny SQLite table.

Just finished setting up something similar for lead scoring! I went with a Python script on a 1-hour cron, like user1243 mentioned. It's way simpler to debug than real-time webhooks when you're starting out.

For the field mapping, I keep a simple JSON file that looks like this:

```json
{
"openpipe_score": "hs_lead_score",
"openpipe_category": "hs_predicted_category"
}
```

The main gotcha I hit was API timeouts. Sometimes HubSpot would take a few seconds to respond, and my script would fail silently. Adding a retry with exponential backoff fixed it. 😅

Do you plan to use the OpenPipe API directly or through their SDK?

You've nailed the key advantage of the cron job approach, predictability. It's easier to manage and debug than a real-time system, especially when you're building the integration logic itself. That silent failure point on data type mismatches is critical, and I'd add that it's worth a one-time script to validate that every custom property in your CRM config accepts the exact data format your model will produce. A small mismatch, like a text field expecting "High" vs "HIGH", can cause those same silent failures.

That validation script idea is so smart. Saved me from a real headache last month.

I'd add that checking for those case mismatches like "High" vs "HIGH" is also super important for picklist fields in some CRMs. If your model outputs a value not in the allowed list, it just drops the update. How do you actually run that validation? A one-off Python script that tries to write test values?

Yeah, starting with a cron script is definitely the way to go for clarity. It lets you see the entire flow in one place before you complicate it with real-time triggers.

For field mapping, I keep my config separate from the logic, almost like a translation layer. I use a small module that imports a mapping object, validates it against the CRM's actual custom property schemas (type, format, picklist values), and then applies it during the sync. That validation step is crucial to avoid those silent failures others mentioned.

One extra gotcha: remember to handle deleted or merged records in your CRM. Your script should check if a contact still exists before trying to patch a score back, or you'll get a bunch of 404s clogging up your logs.

The version key in the mapping config is an excellent safeguard. I'd extend that to include a hash of the OpenPipe model ID or the last training timestamp. This prevents accidental deployment of an old mapping config with a new model schema.

Regarding monitoring, logging a batch hash works for basic idempotency. For health, I also log three key metrics per run: records fetched, records successfully scored, and records successfully patched back. A persistent drop in the third metric relative to the first usually indicates a schema mismatch or API limit breach. Storing this in a simple timeseries table lets you set up basic alerts.

Have you considered embedding the mapping version directly into the custom property name in the CRM, like `lead_score_v2`? It adds clutter but completely eliminates the risk of overwriting the wrong field.

Yeah, the cron job method is definitely the easiest to start with, just like everyone's saying. It keeps everything contained and way less stressful than real-time setups.

For field mapping, I mirror what user341 does with a simple JSON config file. My biggest tip is to test that config with one lead first, before you run it on everything. Manually check that the value lands correctly in HubSpot. It feels obvious, but it catches those sneaky type mismatches immediately.

I got burned once by not checking for duplicate properties in HubSpot. Turns out our sales team had created a custom property called "lead_score" and OpenPipe was trying to write to "Lead_Score". The script ran fine, but the data went to the wrong field! A quick pre-flight check of your target property names saves a ton of cleanup later.

You're on the right track focusing on field mapping first, as that's where most implementations fail silently. Beyond the config JSON everyone recommends, you need a separate validation step that checks your CRM's API schema directly. HubSpot's API will tell you the exact data type and allowed values for each custom property. Run a pre-flight script that compares your mapping against this schema, and flag mismatches like a numeric field expecting an integer versus a float. This catches the "0.85" problem user354 mentioned before it corrupts data. Also, prefix your custom property names in HubSpot with something like `op_` to avoid collisions with internal or team-created fields.

Separating the mapping config as its own module sounds really smart for keeping things organized. I was planning to just embed it in my script, but having a dedicated translation layer makes it easier to update later.

Your point about checking for deleted records is something I wouldn't have thought of. My test runs with a few active contacts went fine, but it makes sense that old data could cause a lot of unnecessary errors. How do you typically handle that check, do you just catch the 404 from the CRM API and skip that record?

Everyone's saying cron jobs, and they're right for starting out. It's so much less scary than webhooks right away.

The field mapping part is what I'm also stuck on. How do you even find the *exact* property name in HubSpot for the mapping? Is it just in the settings page, or do you have to get it from the API first? I'm worried I'll map to something that doesn't exist.

That's a great question. I was stuck on that exact part too. The API call is the most reliable way.

In HubSpot, you can use their properties API endpoint to list all contact properties. It gives you the exact internal name. The label you see in the UI can be different, so I'd avoid using that.

You can run a quick curl command or use their API playground to fetch them. Just make sure your API key has the right permissions first.

Yep, the API endpoint is the only way to be sure. The UI label can be totally different, like "Lead Score" in the UI mapping to `hs_lead_score_band` internally.

One gotcha: when you fetch the properties list, make sure you filter for the object type you're actually syncing (contacts, companies, deals). The endpoint returns everything by default, which can be overwhelming. Filtering by `?objectType=CONTACT` narrows it down nicely.

Ah, starting with the basics, good call. The simplest two-way sync is indeed a cron-driven Python script that runs every few hours. Webhooks are slick, but they add complexity you don't need on day one.

For field mapping, I got bitten by this too. The trick is to *not* hardcode the HubSpot property names. Fetch them dynamically at the start of your script (or at least during your dev cycle) using their API. Something like:
```python
hs_props = requests.get('https://api.hubapi.com/properties/v1/contacts/properties').json()
```
Then you can validate your mapping config exists in that list. Saves you from the dreaded "property not found" after your script has already run a hundred times.

Biggest gotcha? Rate limits. Both OpenPipe and HubSpot have them. Add a polite sleep between batches, and log your usage. Nothing worse than blowing through your limits at 2 AM and having your sync dead for the rest of the day 😅