There's a new version of the HubSpot API

As of November 30, 2022, HubSpot API keys are no longer a supported authentication method for accessing HubSpot APIs. Instead, you should use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

Using global form events

Last updated October 20, 2023

Forms allow two ways to bind functionality onto events; embedded callbacks in the HubSpot form embed code, discussed here, and global events, discussed in this doc.

This is a list of all global events that are emitted by HubSpot forms, and can be used to trigger custom JavaScript. If you need complete control over the styles and actions of your form, it's recommended that you build your own custom form and submit the data using the Forms API.

Please note:

  • These events are non-blocking, so it's not possible to prevent a form submission using the onFormSubmit callback.
  • You cannot change form submission data using onBeforeFormSubmit. When using onBeforeFormSubmit, the form is submitted as the event is emitted to the browser. Any listeners hooked to the events do not block the main thread of the form's execution. For synchronous changes to the form, it is recommended to customize the form embed code instead.

Events and Arguments

When performing custom redirects, please use onFormSubmitted instead of onBeforeFormSubmit and onFormSubmit. A browser redirect via these two events may prevent submissions being initiated, thus preventing form submissions.

onBeforeFormInit

Called before the form has been inserted into DOM.


    // Global event
    {
        type: 'hsFormCallback',
        eventName: 'onBeforeFormInit',
        id: 'Id of form submitted',
        data: {}
    }


onFormReady

Called after the form has been inserted into DOM.


    // Global event
    {
        type: 'hsFormCallback',
        eventName: 'onFormReady',
        id: 'Id of form submitted',
        data: {}
    }


onBeforeFormSubmit

Called at the start of form submission, but before submission has been persisted. Behaves the same as onFormSubmit, but is preferred due to more accurate naming indicating when this event is triggered.


       // Global event
    {
        type: 'hsFormCallback',
        eventName: 'onBeforeFormSubmit',
        id: 'Id of form to submit,
        data: [ // Array containing the names and values of the fields about to be submitted
            {
                name: 'email',
                value: 'test@example.com'
            },
            {
                name: 'firstName',
                value: 'Jane'
            },
            {
                name: 'lastName',
                value: 'Doe'
            }
        ]
    }


onFormSubmit

Called at the start of form submission, but before submission has been persisted. Please use onBeforeFormSubmit instead.


     // Global event
    {
        type: 'hsFormCallback',
        eventName: 'onFormSubmit',
        id: 'Id of form to submit,
        data: [ // Array containing the names and values of the fields about to be submitted  
          {
                name: 'email',
                value: 'test@example.com'
            },
            {
                name: 'firstName',
                value: 'Jane'
            },
            {
                name: 'lastName',
                value: 'Doe'
            }
        ]
    }


onFormSubmitted

Called after the form has been submitted and the submission has been persisted.


    // Global event
    {
        type: 'hsFormCallback',
        eventName: 'onFormSubmitted',
        id: 'Id of form submitted',
        data: {
redirectUrl: "https://example-url.com", // String containing redirect url, if set
submissionValues: { // Object containing key value pairs of submitted data
'email': 'test@example.com',
'firstName': 'Jane',
'lastName': 'Doe'
}
} }