Use webhooks with HubSpot workflows

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 contact 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.

• 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 POST request

• In your HubSpot account, navigate to Automations > Workflows.
• To edit an existing workflow, click the name of the workflow. Or, create a new workflow.
• In the workflow editor, click the + plus icon to add an action.
• In the left panel, in the Data ops section, select Send a webhook.
   

• Click the Method dropdown menu and select POST. 
• 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. You can either use a request signature in your webhook header or use an API key:
  • 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.

• • To use an API key or a public app created through a developer account for authentication:

• • • 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 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.

• To include all properties, select Include all [object] properties. 
• To include only specific properties: 
  
  • Select Customize request body.
  • To customize the request body using a HubSpot property, enter the Key and select a property. To add another property, click Add property.
  • To customize the request body using a static field, enter the Key and Value. To add another property, click Add static value.

• • To remove a property or static value, click the delete trash icon.
• Click Save. 

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

Set up a GET request

• In your HubSpot account, navigate to Automations > Workflows.
• To edit an existing workflow, click the name of the workflow. Or, create a new workflow.
• In the workflow editor, click the + plus icon to add an action.
• In the left panel, in the Data ops section, select Send a webhook.
   

• Click the Method dropdown menu and select 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. You can either use a request signature in your webhook header or use an API key:
  • 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.

• • To use an API key or a public app created through a developer account for authentication:

• • • 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 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.

• To use a HubSpot property as a query parameter: 
  • Under the Query parameters section, enter the Key, then select a property.
  • To add another property, click Add property.
  • To remove a property, click the delete trash can icon. 
• To use a static value as a query parameter: 
  • Under the Query parameters section, enter the Key, then enter a value.
  • To add another property, click Add static value.
  • To remove a property, click the delete trash can icon. 
• Click Save. 

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 your HubSpot account, navigate to Automations > Workflows.
• Click the name of the workflow. 
• In the workflow editor, click the Send a webhook action.
• In the left panel, click Test action to expand the section. 
• If you're testing a POST request, 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.
• Once your workflow has been turned on, you can manually enroll a test contact. 
  
  

• When testing your webhook externally:
  • 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:

• Own a developer account. If you don't have one, sign up for a developer account.
• Own an app. If you don't have an app, learn how to create an app.
• Check the hash value of the signature.

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 Automations > 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, click the View properties or action outputs from dropdown menu and select Webhook trigger. You can then use properties from the connected webhook.