Embedding a HubSpot form is the easy part. The real value comes when your page reacts to the form: firing a conversion event, swapping in a custom thank-you message, or tweaking a field once the form has rendered. HubSpot's embedded forms expose events for exactly this. This guide shows the two ways to use them and the mistakes to avoid.
Two ways to listen
- Callbacks passed to
hbspt.forms.create(). Best when you control the embed code. - Window message events (
hsFormCallback). Best when the form is embedded by a module, a tag manager or code you cannot edit.
Option 1: Callbacks on hbspt.forms.create
<script charset="utf-8" src="//js.hsforms.net/forms/embed/v2.js"></script>
<div id="contact-form"></div>
<script>
hbspt.forms.create({
portalId: "YOUR_PORTAL_ID",
formId: "YOUR_FORM_ID",
region: "na1",
target: "#contact-form",
onFormReady: function ($form) {
// The form is in the DOM and ready to be modified
console.log("Form ready", $form);
},
onFormSubmit: function ($form) {
// Fires when the visitor submits, before the submission completes
},
onFormSubmitted: function ($form, data) {
// Fires after a successful submission
console.log("Submitted", data);
}
});
</script>
Use the region that matches your HubSpot account (for example na1 or eu1); it is shown in your embed code.
What each callback is for
onFormReady: runs after the form renders. Use it to prefill or adjust fields, or to attach extra listeners.onBeforeFormSubmit: runs just before submission, useful for a last-minute check or to read the values.onFormSubmit: runs when the form is submitted.onFormSubmitted: runs once the submission has succeeded. This is the right place for conversion tracking.
Option 2: The hsFormCallback window message
The embedded form also posts messages to the page. You can listen for them without touching the embed:
window.addEventListener("message", function (event) {
if (event.data && event.data.type === "hsFormCallback") {
if (event.data.eventName === "onFormReady") {
// form is ready
}
if (event.data.eventName === "onFormSubmitted") {
// event.data.id is the form ID
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: "hubspot_form_submitted",
formId: event.data.id
});
}
}
});
Always check event.data.type first: message events come from many sources on a page, and your handler will receive all of them.
Practical examples
Push a conversion event to Google Tag Manager
Use the dataLayer.push shown above inside onFormSubmitted. Because it fires only after a successful submission, you avoid counting visitors who click submit but fail validation.
Show a custom thank-you message
onFormSubmitted: function ($form) {
var thanks = document.getElementById("custom-thanks");
if (thanks) { thanks.hidden = false; }
}
Common mistakes
- Tracking on submit instead of submitted. A submit event does not guarantee the form was accepted. Count conversions in
onFormSubmitted. - Not checking the form ID. If a page has several forms, compare
event.data.idwith the form you care about. - Using callbacks with a shortcode or module you do not own. Switch to the window message approach instead.
- Querying the form too early. The form is injected asynchronously, so DOM lookups before
onFormReadywill find nothing. - Ignoring consent. Only fire marketing tags when the visitor has consented. See our guide on the HubSpot cookie banner API.
Testing checklist
- Open the browser console and confirm
onFormReadylogs once per form. - Submit with invalid data and confirm
onFormSubmitteddoes not fire. - Submit a valid entry and confirm your event fires exactly once.
- Check the event in Tag Manager preview or your analytics debug view.
Sources
- HubSpot Developer Docs: Forms embed code and form events (developers.hubspot.com)
- HubSpot Knowledge Base: Embed a HubSpot form on an external site
Note: exact payload fields can change between embed versions, so log data in your own account and confirm against the current HubSpot documentation before relying on a specific property.
