​

Webhook Triggers

• Run enrichment when contact is created
• Start onboarding when deal closes
• Update records when properties change
• Trigger analysis when stage changes
• Send notifications on specific events

​

What This Does (The Simple Version)

​

How It Works

1. HubSpot Workflow - Watches for events (contact created, deal updated, etc.) and sends webhook
2. Agent.AI Workflow - Receives webhook and runs your automation

1. Event happens in HubSpot (e.g., deal closes)
2. HubSpot workflow triggers
3. HubSpot sends webhook (HTTP POST) to Agent.AI
4. Agent.AI workflow starts with data from webhook
5. Agent.AI runs your actions
6. Updates go back to HubSpot

​

Setting It Up

​

Part 1: Create Agent.AI Workflow with Webhook Trigger

1. Click “Create Workflow”
2. Add trigger: Webhook
3. Copy the webhook URL (looks like: https://agent.ai/webhook/abc123)

• contact_id - Contact’s HubSpot ID (required)
• contact_email - Email address
• contact_company - Company name
• Any other contact properties

• deal_id - Deal’s HubSpot ID (required)
• deal_name - Deal name
• deal_amount - Deal amount
• deal_stage - Current stage
• Any other deal properties

• company_id - Company’s HubSpot ID (required)
• company_name - Company name
• company_domain - Domain
• Any other company properties

• _hubspot_portal - Identifies which HubSpot account sent it

​

Part 2: Create HubSpot Workflow that Sends Webhook

1. In HubSpot, go to Automation → Workflows
2. Click Create workflow
3. Choose From scratch

• Contact-based: “Contact is created”, “Contact property changed”
• Deal-based: “Deal stage changed”, “Deal is created”
• Company-based: “Company is created”, “Company property changed”

1. Click + to add action
2. Search for “webhook”
3. Select Send a webhook
4. Click Add action

• Paste the Agent.AI webhook URL from Part 1

• Select POST

• Select JSON

{
  "_hubspot_portal": "{{portal.id}}",
  "object_id": "{{object.hs_object_id}}",
  "property_name": "{{object.property_name}}"
}

{
  "_hubspot_portal": "{{portal.id}}",
  "contact_id": "{{contact.hs_object_id}}",
  "contact_email": "{{contact.email}}",
  "contact_company": "{{contact.company}}",
  "contact_name": "{{contact.firstname}} {{contact.lastname}}"
}

{
  "_hubspot_portal": "{{portal.id}}",
  "deal_id": "{{deal.hs_object_id}}",
  "deal_name": "{{deal.dealname}}",
  "deal_amount": "{{deal.amount}}",
  "close_date": "{{deal.closedate}}",
  "deal_stage": "{{deal.dealstage}}"
}

{
  "_hubspot_portal": "{{portal.id}}",
  "contact_id": "{{contact.hs_object_id}}",
  "lifecycle_stage": "{{contact.lifecyclestage}}",
  "old_value": "{{contact.lifecyclestage.original}}",
  "new_value": "{{contact.lifecyclestage.updated}}"
}

1. Click Save
2. Toggle to On (activate workflow)
3. Test by creating a test record that matches trigger

​

Common Webhook Patterns

​

Contact Enrichment on Creation

{
  "_hubspot_portal": "{{portal.id}}",
  "contact_id": "{{contact.hs_object_id}}",
  "contact_email": "{{contact.email}}",
  "contact_company": "{{contact.company}}"
}

1. Lookup contact details
2. Web search for company
3. AI enrichment analysis
4. Update contact with insights

​

Deal Onboarding on Close

{
  "_hubspot_portal": "{{portal.id}}",
  "deal_id": "{{deal.hs_object_id}}",
  "deal_name": "{{deal.dealname}}",
  "deal_amount": "{{deal.amount}}",
  "close_date": "{{deal.closedate}}"
}

1. Lookup deal + associations
2. Get engagement history
3. AI onboarding plan
4. Create timeline events

​

Lead Scoring on Update

{
  "_hubspot_portal": "{{portal.id}}",
  "contact_id": "{{contact.hs_object_id}}",
  "job_title": "{{contact.jobtitle}}",
  "company": "{{contact.company}}",
  "email": "{{contact.email}}"
}

1. Lookup full contact
2. Calculate lead score
3. Update contact with score
4. If high score → notify sales

​

Testing Your Webhook

​

Test in Agent.AI First

1. Go to your Agent.AI workflow
2. Click Test or Run
3. Manually enter test webhook data
4. Verify workflow runs correctly

{
  "_hubspot_portal": "12345678",
  "contact_id": "123456",
  "contact_email": "[email protected]",
  "contact_company": "Test Company"
}

​

Test HubSpot Workflow

1. In HubSpot workflow, click Test
2. Select a test record (contact, deal, etc.)
3. Click Test action
4. HubSpot sends webhook to Agent.AI
5. Check Agent.AI execution log

​

Check Execution Log

1. Go to workflow
2. View Executions or History
3. See webhook data received
4. Check if all variables arrived
5. Debug any issues

​

Troubleshooting

​

Webhook Not Triggering

1. HubSpot workflow not activated
2. Test record doesn’t match trigger criteria
3. Webhook URL incorrect

1. Check HubSpot workflow is On
2. Verify trigger conditions match test record
3. Copy/paste webhook URL again from Agent.AI
4. Check HubSpot workflow history for errors

​

Variables Missing in Agent.AI

1. Property not populated in HubSpot
2. Wrong property name in payload
3. Syntax error in JSON

1. Check HubSpot record has those properties filled
2. Verify exact property names (case-sensitive)
3. Test JSON payload in HubSpot workflow test mode
4. View Agent.AI execution log to see what was received

​

Wrong Portal ID

1. _hubspot_portal missing from payload
2. Not connected to correct HubSpot account

1. Always include "_hubspot_portal": "{{portal.id}}" in payload
2. Verify correct HubSpot account connected in Agent.AI

​

HubSpot Shows Webhook Error

1. Agent.AI webhook URL changed
2. Agent.AI workflow deleted
3. Network issue

1. Get fresh webhook URL from Agent.AI
2. Update in HubSpot workflow
3. Test again
4. Check Agent.AI workflow still exists

​

Tips & Best Practices

• Always include _hubspot_portal in payload
• Always include object ID (contact_id, deal_id, etc.)
• Test with sample records first
• Use descriptive variable names
• Keep payload simple - only essential properties
• Check execution logs after testing
• Use HubSpot workflow test mode

• Send entire object (only needed properties)
• Forget to activate HubSpot workflow
• Use webhooks for batch operations (use scheduled instead)
• Assume properties are always filled
• Include sensitive data in webhook
• Create circular webhooks (Agent.AI → HubSpot → Agent.AI)

• Webhooks trigger instantly (under 1 second)
• Agent.AI workflow starts immediately
• Total time depends on actions inside workflow
• Typical enrichment: 5-15 seconds end-to-end

• Use {{object.hs_object_id}} for object ID
• Use {{portal.id}} for portal ID
• Property names match HubSpot internal names
• Use {{property.original}} for old value
• Use {{property.updated}} for new value

​

Related Resources

• Contact Enrichment - Webhook on contact created
• Customer Onboarding - Webhook on deal closed

• HubSpot Setup - Initial connection setup
• Template Variables - Using {{variables}} in Agent.AI
• Troubleshooting - Common webhook issues

• Lookup HubSpot Object (V2) - Get full object details
• Update HubSpot Object (V2) - Update after processing