Introduction

Many companies use HubSpot custom objects to model business processes unique to them. With the Oneflow and HubSpot integration, you can automatically create Oneflow contracts directly from these custom objects.

Benefits

• Automate contract creation from any custom object.
• Eliminate manual data entry and reduce errors.
• Keep HubSpot and Oneflow fully synced.
• Centralize signed contracts on HubSpot records.

Example Business Scenario

Imagine a company called EduTech Services, which delivers training programs to universities.

Instead of using HubSpot’s standard Deals object, they’ve created a custom object called Enrollments to manage student applications. Each enrollment record contains information such as University name, Enrollment status, Course name, and the Assigned course leader.

Their desired workflow is:

1. Workflow 1: When an enrollment status is updated to "Pending approval," a contract is automatically created in Oneflow and sent to the student.
2. Workflow 2: After the contract is signed by all parties, the final PDF is automatically saved back to the student's Enrollment record in HubSpot.

Workflow 1

Step 1: Define Your Trigger in a HubSpot Workflow

• In HubSpot, create a workflow:
  • Workflow Type: Based on the Enrollments custom object.
    

Set up the trigger: The trigger could be when a student’s Enrollment's stage property is updated to Approved.

Step 2: Configure the "Create contract" action

Inside the HubSpot workflow, add the Oneflow: Create Contract action.

• Workspace: Select your Oneflow workspace.
• Template: Choose the right Oneflow template (e.g., "Training Services Agreement").

Map data from the Enrollment record into Oneflow contract data fields in Two-way sync settings.

For advanced action configuration details, see Workflows: Create a contract.

Step 3: Add the ‘Add participants to a contract’ action

Use the Add Participants action to automatically pull in contacts associated with your Enrollment record and add them as participants to the Oneflow contract.

For advanced action configuration details, see Workflows: Add participants.

• Specify the Contract: Identify the target contract by selecting its ID from a previous workflow step or by entering it manually.
• Define the Participant: Add a participant as an individual, part of a company, or a colleague. Their details can be sourced by:
  • Mapping to existing HubSpot properties,
  • Entering details manually, or
  • Adding all contacts associated with the HubSpot record.
• Assign a Role: Choose a role to determine permissions:
  • Signatory: Can sign
  • Influencer: Can edit
  • Viewer: Can comment
  • Organizer: Internal colleague role

Step 4: Add the 'Send contract' action

Add the Send contract action to automatically send the generated contract to the participants.

• Get contract ID by: Use the output from the Create contract action.
• Subject and Message: Customize the invitation email that the participant will receive.
  

Step 5: Create and update the Contract ID Property

Create a Contract ID property

First, create a custom property on your object (in this case, Enrollments) to store the ID of the Oneflow contract.

1. In HubSpot settings, navigate to Properties.
2. Select your custom object (e.g., Enrollments).
3. Create a new property. Set the Property label to Contract ID.
   
4. On the Field type tab, set the field type to Number.
5. On the Rules tab, enable Require unique values for this property.

   This property is crucial for Workflow 2 to identify which contract to download.

   The final step in this workflow is to save the new contract’s ID back to your custom object.

6. Go back to your workflow and add a Copy property value action.
   

• Property to copy from: Select the Contract ID from the output of the Create Contract action.
• Property to copy to: Select the custom Contract ID property you created earlier on your Enrollment object. Click Save.
  

Workflow 2

This second workflow listens for a signed contract in Oneflow and saves the PDF back to the custom object in HubSpot (Enrollments, in this example). It is a webhook-based workflow.

Step 1: Set up the Webhook Trigger in HubSpot

1. Navigate to Automation > Workflows in HubSpot and click Create workflow > From scratch.
2. Click Set up triggers, and in the right panel, select When a webhook is received.
   
3. Click Add webhook.
4. Assign a name to the webhook.
5. HubSpot will generate a unique Webhook URL. Copy and save this URL securely for the next steps.
   
6. Test the webhook using the JSON structure below as an example payload that HubSpot will forward to your workflow:
   Note
   Use a tool that can make API calls (for example: Postman or cURL) to POST the test payload to your HubSpot webhook URL.

   {
     "contract": {
       "id": 123
     },
     "callback_id": "xxx",
     "events": [
       {
         "created_time": "20250915T0513330000",
         "id": 456,
         "state": "signed",
         "type": "contract:sign"
       }
     ]
   }

   cURL command for testing: You may use this command, replacing the HubSpot webhook URL with your actual values:

   curl --location '<HubSpot webhook URL>' \
   --header 'Content-Type: application/json' \
   --data '{
     "contract": {
       "id": 123
     },
     "callback_id": "xxx",
     "events": [
       {
         "created_time": "20250915T0513330000",
         "id": 456,
         "state": "signed",
         "type": "contract:sign"
       }
     ]
   }'

7. Configure data types: In the webhook trigger configuration in HubSpot, set the appropriate data types for incoming fields. Ensure the contract ID is configured as an integer / number type.
   
8. Map the incoming contract ID: In the webhook trigger settings, map the incoming contract ID to your custom Contract ID property so that later workflow steps can reference it.
   This ensures the contract ID from the webhook is stored in your HubSpot record.
   
9. Attach the webhook trigger to the workflow: Go back to the workflow editor, click the trigger, and select the webhook trigger you just created under Enrollment-based webhook events.
   
10. Click Save.Your workflow’s trigger should now look like the following.

Step 2: Add the ‘Download contract’ action

1. Add the Download contract action from the Oneflow options.
2. Configure the action to find and save the correct contract:

• Get contract ID by: Select Enter contract ID.
• Contract ID: Use the webhook body field contract.id.
  
• Save contract PDF to…: Select Yes to attach it to the parent record.
• Select the HubSpot object…: Choose your custom object (e.g., Enrollments). You’ll need the Object Type ID from HubSpot’s API.
• HubSpot Object ID: Use the webhook body field contract.meta.hs_deal_id.
• Attach contract to: Select Attachments section.
  

Now, whenever a contract created from an Enrollment is signed, this second workflow will trigger and automatically attach the signed PDF to the correct record in HubSpot.

Step 3: Create the Webhook in Oneflow

1. In your Oneflow account, go to Admin > Workflows > API tokensand generate a new token if you don’t have one.
   
   
   Important: Save this token securely for the next step.
   
2. Send the following CURL request, replacing <HubSpot URL> with your HubSpot webhook URL and <token> with your Oneflow API token:

curl --location 'https://api.oneflow.com/v1/webhooks' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-oneflow-api-token: <token>' \
--data '
{
  "filters": [
    {
      "filter_rules": [
        {
          "type": "EVENT_TYPE",
          "values": [
            "contract:sign"
          ]
        }
      ]
    }
  ],
  "callback_url": "<HubSpot URL>"
}'