Webhooks - Spark OS Documentation

Webhooks are the universal connector. They let any external system — form builders, CRMs, marketing tools, custom apps — send data directly into your Spark workspace. When a webhook fires, your agent processes the incoming data and takes action. This is how most lead capture works: a form on your website sends a submission to Spark, and your agent handles it automatically.

How Webhooks Work

Spark gives you a unique webhook URL for your workspace
You configure an external system to send data (POST requests) to that URL
When data arrives, it triggers your agent
Your agent processes the data according to your automation rules

The external system sends a JSON payload — your agent reads it, extracts the relevant fields, and does whatever you’ve configured: create a contact, score the lead, send an email, create tasks, etc.

Setting Up a Webhook

Get Your Webhook URL

Navigate to Settings → Integrations → Webhooks. Your unique webhook URL is displayed here. Copy it.

Configure the External System

In your form builder, CRM, or external tool, find the webhook or HTTP notification settings. Paste your Spark webhook URL as the destination.

Set Up an Automation

Go to the Automations tab and create an automation with the Webhook Received trigger. Define what your agent should do when data arrives.

Test It

Submit a test entry from your form (or send a test payload). Verify that your agent processes it correctly in the automation run history.

Compatible Form Providers

Webhooks work with virtually any system that can send HTTP POST requests. Common form and lead-capture tools:

Typeform

Webhooks under Typeform’s Connect tab

Google Forms

Webhook integration in form settings

Google Forms

Via Apps Script or a connector like Zapier

Jotform

Webhooks in form settings → Integrations

Gravity Forms

Webhooks add-on for WordPress

Custom Forms

Any form that can POST JSON to a URL

Connecting Popular Providers

Typeform

Open your Typeform form → Connect tab
Click Webhooks
Click Add a webhook
Paste your Spark webhook URL
Toggle it on
Submit a test response to verify

Typeform sends a JSON payload with all form fields including answers, metadata, and submission timestamps.

Google Forms

Open your form in Google Forms
Go to Settings → Integrations → Webhooks
Click Add Webhook
Set the URL to your Spark webhook URL
Choose POST as the method
Select which form fields to include
Save and test with a sample submission

Jotform

Open your form → Settings → Integrations
Search for Webhooks
Paste your Spark webhook URL
Save and test

Custom / API

Send a POST request to your webhook URL with a JSON body:

curl -X POST https://app.runspark.ai/webhook/your-workspace-id \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jordan Smith",
    "email": "jordan@acme.com",
    "phone": "555-123-4567",
    "company": "Acme Corp",
    "message": "Interested in the Professional tier for 30 users"
  }'

Your agent receives the JSON payload and processes it based on your automation rules.

Writing Webhook Automation Actions

The automation action for webhook-triggered events should tell your agent how to process the incoming data. Be explicit about field mapping:

A new form submission arrived via webhook. Process it as follows:

1. Extract the contact details: name, email, phone, company
   - The form fields may be named differently (e.g., "full_name", 
     "email_address", "phone_number") — map them to the right 
     CRM fields

2. Check if a contact with this email already exists
   - If yes: update their record and add a note about the new submission
   - If no: create a new contact

3. Read their message/inquiry and score the lead:
   - Mentions pricing, demo, or is ready to buy → Hot
   - Asks about specific features or services → Warm  
   - General inquiry → Cool

4. Set pipeline stage based on score

5. Create a follow-up task with appropriate urgency

6. Post a summary to chat

Different form providers send data in different formats. When setting up a new webhook source, send a test submission first and check the automation run history to see the exact payload structure. Then adjust your automation action to match the field names.

Webhook Payload Format

Your agent receives the raw JSON payload from the external system. It doesn’t need to match a specific schema — your agent reads whatever structure is sent and extracts the relevant information. Common payload patterns:

Simple Key-Value
Nested (Typeform-style)
Form-style

{
  "name": "Jordan Smith",
  "email": "jordan@acme.com",
  "phone": "555-123-4567",
  "message": "I'd like a demo"
}

{
  "form_response": {
    "answers": [
      {
        "field": { "ref": "name" },
        "text": "Jordan Smith"
      },
      {
        "field": { "ref": "email" },
        "email": "jordan@acme.com"
      }
    ]
  }
}

{
  "First_Name": "Jordan",
  "Last_Name": "Smith",
  "Email": "jordan@acme.com",
  "Phone": "555-123-4567",
  "Description": "Looking for enterprise pricing"
}

Your agent handles all of these — just describe in your automation action what fields to look for and how to process them.

Security

Your webhook URL is unique to your workspace — treat it like a password
Only share it with systems you trust
If you suspect your URL has been compromised, you can regenerate it from Settings → Integrations → Webhooks

Regenerating your webhook URL invalidates the old one immediately. Any external systems using the old URL will stop sending data to your workspace. Update all connected systems with the new URL after regenerating.

Testing

Before connecting production forms, test your webhook setup:

Copy your webhook URL
Use a tool like curl, Postman, or an online webhook tester to send sample data
Check the Automations run history to see how your agent processed it
Adjust your automation action based on the results
Once everything works, connect your real forms

This avoids real leads being misprocessed while you’re still tuning the automation.

​How Webhooks Work

​Setting Up a Webhook

​Compatible Form Providers

Typeform

Google Forms

Google Forms

Jotform

Gravity Forms

Custom Forms

​Connecting Popular Providers

​Writing Webhook Automation Actions

​Webhook Payload Format

​Security

​Testing

How Webhooks Work

Setting Up a Webhook

Compatible Form Providers

Connecting Popular Providers

Writing Webhook Automation Actions

Webhook Payload Format

Security

Testing