topic Re: Custom Event via API in APIs & Integrations

Custom Event via API

Arpit_Verma — Thu, 17 Apr 2025 11:11:41 GMT

Hi Community,

I'm currently setting up a custom event via API for an existing Private App in HubSpot. While I’ve successfully created the custom event (name only), I’m unsure how to associate this event with the Private App integration, specifically to trigger when new contacts are created through it.

As someone without a development background, I’m struggling with the technical aspects such as authentication, tracking codes, and data mapping. It’s not clear to me if the tracking code provided at the end of custom event setup needs to be handed off to the Private App development team or how this integration works under the hood.

My end goal is to:

Capture this event when contacts come through the Private App
Map 5 of the default contact properties
Use the custom event to build a Revenue Attribution report for that private app

Would greatly appreciate a simplified, step-by-step guide or any resources tailored for non-technical users.

Thanks in advance!

Re: Custom Event via API

RubenBurdin — Fri, 18 Apr 2025 05:01:12 GMT

Hey @Arpit_Verma

been through this before and yeah, it gets confusing fast if you’re not in the weeds with API stuff.

So you’re on the right track — you’ve created the custom event, but by default HubSpot doesn’t “know” when to fire it unless you trigger it manually. The tracking code you got is mostly used for web-based tracking, not private app logic. So if you want the event to fire when a contact is created through your private app, your devs need to explicitly send that event to HubSpot when that happens.

They’ll need the event ID you got, and then they’ll make a POST request to HubSpot’s /events/v3/send endpoint using your app’s token. No need to overthink the contact property mapping part — you can keep the default contact properties as-is and just make sure the event is logged right when the contact is created.

That way, you’ll be able to use it later in attribution reporting since HubSpot can treat that event as a touchpoint. So yeah, it’s less about “connecting” the event to the private app and more about making sure the app tells HubSpot: “hey, this contact just triggered this event.” If it helps, just tell your devs: here’s the event ID, send it to /events/v3/send when a new contact is created, and that’ll give us what we need to track attribution properly. Let me know if you want help drafting the exact message for them.

Ruben Burdin

Real-Time Data Sync Between any CRM or Database | Founder @Stacksync (YC W24)

Re: Custom Event via API

Arpit_Verma — Sun, 20 Apr 2025 18:18:46 GMT

Hi @RubenBurdin,

Thank you for your response — it was very helpful.

I need further assistance regarding the Forms API. We currently have a Private App Integration built on the Contacts API. The external platform we use submits a non-HubSpot form that creates a contact in HubSpot. However, due to the current setup, these contacts aren't attributed at the interaction source level.

I've been advised to migrate to the Forms API to ensure proper source attribution and accurate reporting in the Attribution report.

As a non-developer, I’m unsure of the best approach. Should I ask the team managing the Private App Integration to update it to use the Forms API, or would it be better to work with a HubSpot developer to handle the transition?

Or even if we have to do this myself, how should this be done? I've already gone and studies the HubSpot Knowledge academy docs related to this. Need a simple stepwise approach which would enable a Non-technical individual like me to achieve this.

Thanks,

Re: Custom Event via API

RubenBurdin — Sun, 20 Apr 2025 21:02:04 GMT

Hey! Totally get where you're coming from .

I’ve seen this situation before, and yeah, switching to the Forms API is usually the move if you want cleaner attribution (like seeing that the contact came from a form submission vs just “API” in reports). So yes, if you’ve got a Private App that currently creates contacts using the Contacts API, that bypasses the attribution logic HubSpot uses for forms, which is why you’re not seeing source info or meaningful touchpoints in attribution reports. To fix that, you’ll want your external platform to send that data to HubSpot using the Forms API instead. That way, HubSpot knows “hey, this was a form submission” and it logs source info like session, page URL, and referrer.

Now, in terms of who should do it: if you’ve already got a dev team working on the private app, it’s 100% fine to ask them to switch that endpoint to use the Forms API instead of the Contacts API. It’s not a huge change technically — they just need to POST the submission to /submissions/v3/integration/submit/:portalId/:formGuid and include things like the fields, legal consent (if needed), and optionally a tracking cookie (hutk) to tie the session.

If you don’t have dev support and want to try it yourself, it’s doable but you’d need to use a platform like Postman or n8n to send the POST requests manually (and you’d still need access to the form GUID and know which contact properties are being sent).

But honestly, if you’ve already got developers involved, it’s faster and safer to just pass this task to them — just tell them: “Can we update our contact creation logic to use the HubSpot Forms API instead of the Contacts API so we get proper source attribution?” and share this doc: https://developers.hubspot.com/docs/api/marketing/forms.

That’s it. You don’t need to rebuild your forms — you can keep using your external form on your site, but just change where the data gets POSTed. Let me know if you want help writing the exact request for your devs or mapping which contact fields should go into which form fields.

Ruben Burdin

Real-Time Data Sync Between any CRM or Database | Founder @Stacksync (YC W24)

Re: Custom Event via API

Arpit_Verma — Mon, 21 Apr 2025 09:17:26 GMT

@RubenBurdin would be glad if you could share the exact request. Will make my work easier.

Thanks