Skip to content

Use webhooks with HubSpot workflows

Last updated: February 21, 2024

Available with any of the following subscriptions, except where noted:

Operations Hub Professional, Enterprise

Use webhooks in workflows to send or retrieve information between HubSpot and other external tools. There are a variety of uses for webhooks, examples of popular use cases for webhooks include:

  • Posting HubSpot contacts data to another system, such as a CRM, when that contact fills out a particular form on your site.

  • Sending deal data to an external shipment-handling system to create a purchase order.

  • Sending chat alerts from your external system to your company's chat stream to notify employees that something important has occurred.

  • Retrieving data from another system to update your HubSpot records. 

You can send both POST and GET requests using workflows. HubSpot regulates webhook traffic separately from other workflow processes. This is done to streamline workflow and webhook performance. When a webhook is slow or times out, the workflow action may take longer than expected to execute.

Please note: HubSpot will retry failed webhooks for up to three days, starting one minute after failure. Subsequent failures will be retried at increasing intervals, with a maximum gap of eight hours between tries. Workflows will not retry after receiving 4XX series response status codes.
One exception to this rule is 429 rate limit errors; workflows will automatically retry after receiving a 429 response, and will respect the Retry-After header if present. Retry-After is recorded in miliseconds. Learn about specific error code exceptions in HubSpot's developer documentation.

Learn more about webhooks in the developers webhooks documentation. If you have questions about your specific implementation of webhooks with HubSpot, reach out on the HubSpot Developers Forums.

Set up a webhook in your workflow

  • In your HubSpot account, navigate to Automation > Workflows.
  • Click the name of the workflow.
  • Click the + icon to add an action.
  • In the left panel, select Send a webhook.
  • Click the Method dropdown menu, then select POST or GET
  • Enter the webhook URL. Webhook URLs are restricted to a secure protocol and must begin with HTTPS. To request specific information, you can add query parameters such as ?queryparameter=abc to the Webhook URL. If no query parameters have been added, a generic POST or GET request will be sent. 
  • Set up your authentication type to authenticate requests to your webhook: 
    • To use a request signature in your webhook header: 
      • Click the Authentication type dropdown menu. Then, select Include request signature in header.
      • Then, enter your HubSpot App ID. Learn how to verify request signatures.
    • You can also use an API key or a public app created through a developer account for authentication.

Please note: as of November 30, 2022, HubSpot API Keys are being deprecated and are no longer supported. You can still use external API keys for authentication in HubSpot workflows.

      • When using an API key for authentication, the API key name and API key location used are dependent on how the webhook is configured. For security reasons, the API key will not display in any test requests. To use an API key: 
        • Click the Authentication type dropdown menu. Then, select API key
        • Enter your API key name.
        • Click the API key location dropdown menu. Then, select either Query parameters or Request header. Learn more about using API keys in HubSpot.
      • If you're making a request to one of our HubSpot API's:
        • Click the API key dropdown menu and select a secret. The secret value must be in the format Bearer [YOUR_TOKEN].
        • Set the value of API key name to Authorization.
        • Set the value of API key location to Request Header.
  • If you're setting up a POST request, you can choose to include all properties from the CRM record or to send only specific properties:
    • To include all properties, under the Customize request body section, select Include all properties
    • To include only specific properties: 
      • Under the Customize request body section, select Choose specific properties.
      • Click the Choose property dropdown menu. Then, click [object] in this workflow and select a property.
      • To change a property's name in the webhook, edit the Property name text field. This will only update the property name in the POST request, it will not update the property name or internal name in HubSpot. 
      • To add another property, click Add property.
      • To remove a property, click the delete trash can icon
         


  • If you're setting up a GET request, you can use properties as query parameters: 
    • Under the Query parameters section, click the Choose property dropdown menu. Then, click [object] in this workflow and select a property.
    • To change a property's name in the query parameter, edit the Property name text field. This will only update the property name in the GET request, it will not update the property name or internal name in HubSpot. 
    • To add another property, click Add query parameter.
    • To remove a property, click the delete trash can icon
  • Click Save



Please note: to select multiple outputs, the response should be structured as a JSON object.

Customize your POST request

If you're setting up a POST request, you can choose to include all properties from the CRM record or to send only specific properties:

  • To include all properties, under the Customize request body section, select Include all properties
  • To include only specific properties: 
    • Under the Request body section, select Customize request body.
    • Enter the Key and Value.
    • To change a property's name in the webhook, edit the Key text field. This will only update the property name in the POST request, it will not update the property name or internal name in HubSpot. 
    • To add another property, click Add property.
    • To remove a property, click the delete trash icon

send-post-webhook-request

Customize your GET requests

If you're setting up a GET request, you can use properties as query parameters to retrieve specific data: 

  • Under the Query parameters section, enter the Key, then select a property.
  • To change a property's name in the query parameter, edit the Property name text field. This will only update the property name in the GET request, it will not update the property name or internal name in HubSpot. 
  • To add another property, click Add property.
  • To remove a property, click the delete trash can icon
  • Select an Authentication type from the dropdown menu.
  • Click Save

send-webhook-get-method

Test your webhook within HubSpot

When setting up your POST or GET webhook, you can execute a test to view the webhook response. During the test, while data is sent to and retrieved from a third party, existing records in HubSpot will not be affected. If you're using an API key for authentication, the API key will not display in any test requests.

After testing your webhook, you can select which fields to output for use as inputs later in your workflow. Select only outputs available in every response. If the output is used in a later action but is not available in the response, the action will fail. 

  • In the side panel, click Test action to expand the section. 
  • Click the Object dropdown menu, then select a Record to test with.
  • Click Test
  • To check the webhook details, select the Response or Request tab. On each tab, you can click Open all to expand all sections, or Collapse all to collapse all sections. 
    • In the Response tab, click headers: or body: to expand each section. 
    • In the Request tab, click httpHeaders: to expand the section.

Test your webhook externally

After you create your workflow with a webhook action, you can run a quick test with a dummy webhook URL:

  • In your browser, navigate to https://webhook.site and copy the unique URL.
  • In the Webhook URL field in your webhook action, paste the URL.

If a webhook action with a POST request is triggered, a JSON response body will be sent to the webhook containing all information about the contact, including form submissions, list memberships, and all contact property values. The receiving system can then parse the JSON data, and use it for its own application.

If a webhook action with a GET request is triggered, a generic GET request will be sent, unless additional query parameters have been applied. 

Please note: historical property values will only be returned in contact-based workflows. Webhooks used in all other workflow types will only return the most recent value.

Verify request signatures in workflow webhooks

Where you've selected Request signature in the Authentication section for your Trigger a webhook action, HubSpot will populate the webhook with a X-HubSpot-Signature header with a SHA-256 hash of the concatenation of the app-secret for your application, the HTTP method, the URI, and the unparsed body. Learn more about this in the developers documentation.

To verify that the requests received at your URL are from HubSpot:

Trigger workflows from webhooks

Webhooks can be used to trigger workflows. When data changes in a third party app, this can trigger a workflow. Learn more about triggering workflows from webhooks.

Use webhook data in the data panel

Data from the webhook connected to your account can be used for certain actions in the data panel.

To use data from the connected webhook:

  • In your HubSpot account, navigate to Automation > Workflows.
  • Click the name of your workflow.
  • Click the + plus icon to add an action.
  • In the left panel, select an action that uses the data panel.
  • In the data panel, under Enrollment properties you can select one of the properties from the connected webhook.
enrollment-properties-webhooks
Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.