> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runspark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive data from any external system via webhooks

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

1. Spark gives you a unique **webhook URL** for your workspace
2. You configure an external system to send data (POST requests) to that URL
3. When data arrives, it triggers your agent
4. 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

<Steps>
  <Step title="Get Your Webhook URL">
    Navigate to **Settings → Integrations → Webhooks**. Your unique webhook URL is displayed here. Copy it.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Compatible Form Providers

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

<CardGroup cols={3}>
  <Card title="Typeform" icon="t">
    Webhooks under Typeform's Connect tab
  </Card>

  <Card title="Google Forms" icon="g">
    Webhook integration in form settings
  </Card>

  <Card title="Google Forms" icon="google">
    Via Apps Script or a connector like Zapier
  </Card>

  <Card title="Jotform" icon="j">
    Webhooks in form settings → Integrations
  </Card>

  <Card title="Gravity Forms" icon="g">
    Webhooks add-on for WordPress
  </Card>

  <Card title="Custom Forms" icon="code">
    Any form that can POST JSON to a URL
  </Card>
</CardGroup>

## Connecting Popular Providers

<AccordionGroup>
  <Accordion title="Typeform">
    1. Open your Typeform form → **Connect** tab
    2. Click **Webhooks**
    3. Click **Add a webhook**
    4. Paste your Spark webhook URL
    5. Toggle it on
    6. Submit a test response to verify

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

  <Accordion title="Google Forms">
    1. Open your form in Google Forms
    2. Go to **Settings → Integrations → Webhooks**
    3. Click **Add Webhook**
    4. Set the URL to your Spark webhook URL
    5. Choose POST as the method
    6. Select which form fields to include
    7. Save and test with a sample submission
  </Accordion>

  <Accordion title="Jotform">
    1. Open your form → **Settings** → **Integrations**
    2. Search for **Webhooks**
    3. Paste your Spark webhook URL
    4. Save and test
  </Accordion>

  <Accordion title="Custom / API">
    Send a POST request to your webhook URL with a JSON body:

    ```bash theme={null}
    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.
  </Accordion>
</AccordionGroup>

## 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
```

<Tip>
  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.
</Tip>

## 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:

<Tabs>
  <Tab title="Simple Key-Value">
    ```json theme={null}
    {
      "name": "Jordan Smith",
      "email": "jordan@acme.com",
      "phone": "555-123-4567",
      "message": "I'd like a demo"
    }
    ```
  </Tab>

  <Tab title="Nested (Typeform-style)">
    ```json theme={null}
    {
      "form_response": {
        "answers": [
          {
            "field": { "ref": "name" },
            "text": "Jordan Smith"
          },
          {
            "field": { "ref": "email" },
            "email": "jordan@acme.com"
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="Form-style">
    ```json theme={null}
    {
      "First_Name": "Jordan",
      "Last_Name": "Smith",
      "Email": "jordan@acme.com",
      "Phone": "555-123-4567",
      "Description": "Looking for enterprise pricing"
    }
    ```
  </Tab>
</Tabs>

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**

<Warning>
  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.
</Warning>

## Testing

Before connecting production forms, test your webhook setup:

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

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