Webhooks

Spara's Webhook support completely customizable configurations.

The Spara platform offers powerful integration capabilities through both outbound webhooks and a Web API.

Webhooks provide real-time notifications of lead events via POST requests to a customer-defined endpoint, enabling automated workflows, external system synchronization, and timely responses to key updates. APIs allow customers to update and enrich lead data, manage user information, and influence the behavior of our AI engine - supporting deep, flexible integrations. All API interactions must be conducted over HTTPS to ensure secure communication.

Both webhooks and API support basic data types via JSON. These types are not explicitly identified in request values.

string, ex. "John Doe"
integer, ex. 100
boolean, i.e. true or false

Malformed values will be rejected, ex. John Doe. Take care to not cast integer or boolean values as strings, ex. "100".

Important: Spara does not recommend using webhooks to update information also being updated by a native integration, as this may result in data conflicts or unexpected behavior.

For example, using information from webhooks to update Salesforce records in conjunction with Spara's native Salesforce integration.

Schema

Spara models leads as a single object with any number of arbitrary fields. For example, if you configure Spara to ask your leads the question "What industry is your company in?" you may decide to name that field industry.

The following fields are standard for all leads:

# Info about the lead.
email(string)
company_name (string)
first_name (string)
last_name (string)
phone_number (string)
job_title (string)
num_employees (integer)

In addition, some leads may have an assigned sales rep in Salesforce:

# Info about Salesforce objects connected to the lead. All fields are strings.
sales_rep_name
salesforce_account_id- The unique identifier of the Salesforce account
salesforce_account_name - The name of the Salesforce account which usually represents the company name
salesforce_account_owner_email - The email address of the Salesforce account owner (account's default sales rep)
salesforce_account_owner_id - The unique identifier of the Salesforce account owner
salesforce_account_owner_name - The first & last names of the Salesforce account owner
salesforce_account_website - The website URL associated with the Salesforce account
salesforce_assigned_sales_rep_email - The email address of the lead's assigned sales rep
salesforce_assigned_sales_rep_id - The unique identifier of the lead's assigned sales rep
salesforce_assigned_sales_rep_name

Webhook Supported Events

Spara currently supports the following webhook events:

lead.created - Triggered when a new lead is created
lead.updated - Triggered on message sends and/or field updates

Please note that lead.updated will not be triggered when fields are updated via an API endpoint (see API section below).

Webhook Registration

Each customer can register one webhook endpoint in the Settings > Webhooks page.

The following information is required when registering a webhook:

Webhook URL: A valid HTTPS endpoint where webhook payloads will be sent. Test payloads may be triggered by clicking the "Test" button.
API Key(s): Customers must create at least one API Key to enable outbound webhooks.

Delivery Format

Each webhook is sent as a JSON payload in the body of an HTTP POST request. All known fields about a lead will be returned in each webhook event. The standard format is as follows:

POST /your-endpoint
Content-Type: application/json
X-API-Key: <API Key>

// lead.created
{
  "event": "lead.created",
  "timestamp": "2025-09-18T18:48:08Z",
  "object": "lead",
  "id": "GTvcBRZd",
  "url": "https://app.spara.co/conversations/GTvcBRZd",
  "created_at": "2025-09-18T18:48:08Z",
  "updated_at": "2025-09-18T18:48:08Z",
  "data": {
    "ip_country": "US",
    "ip_region": "New York",
    "ip_city": "New York",
    "current_url": "https://www.my-site.co/chat/jJyVt7TQ5",
    "conversation_url": "https://app.spara.co/conversations/GTvcBRZd"
  },
  "conversation": {
    "created_at": "2025-09-18T18:48:08Z",
    "initial_url": "https://www.my-site.co/chat/jJyVt7TQ5",
    "messages": []
  }
}

// lead.updated
{
  "event": "lead.updated",
  "timestamp": "2025-09-18T18:48:38Z",
  "object": "lead",
  "id": "GTvcBRZd",
  "url": "https://app.spara.co/conversations/GTvcBRZd",
  "created_at": "2025-09-18T18:48:08Z",
  "updated_at": "2025-09-18T18:48:38Z",
  "data": {
    "ip_country": "US",
    "ip_region": "New York",
    "ip_city": "New York",
    "current_url": "https://www.my-site.co/chat/jJyVt7TQ5",
    "conversation_url": "https://app.spara.co/conversations/GTvcBRZd",
    "first_name": "Jane"
  },
  "conversation": {
    "created_at": "2025-09-18T18:48:08Z",
    "initial_url": "http://localhost:5001/chat/jJyVt7TQ5",
    "messages": [
      {
        "sent_by": "AI",
        "created_at": "2025-09-18T18:48:08Z",
        "text": "Hi, any questions I can help with?",
        "asset": "ACME Overview.mp4"
      },
      {
        "sent_by": "LEAD",
        "created_at": "2025-09-18T18:48:13Z",
        "text": "hi my name is Jane"
      },
      {
        "sent_by": "AI",
        "created_at": "2025-09-18T18:48:16Z",
        "text": "Hello! How can I assist you with Acme-Eng's services today?"
      },
      {
        "sent_by": "MANUAL",
        "created_at": "2025-09-18T18:48:38Z",
        "text": "Hi this is your sales rep. I am taking over the conversation."
      }
    ]
  }
}

Security

To ensure secure transmission, all webhook payloads include the customer's oldest active API Keys in the X-API-Key header. Customers should verify the API Key before trusting the contents of the webhook.

Webhook URLs must use HTTPS. Plain HTTP endpoints will be rejected during registration.

Retry Policy

If a webhook delivery fails (i.e., a non-2xx HTTP response or a timeout), our system will automatically retry the request using exponential backoff. Up to 2 retries (in addition to the original attempt) will be made. Customers are encouraged to design their endpoints to respond quickly and handle retries idempotently.

Best Practices

Validate the API Key of incoming webhook requests before processing.
Respond to webhooks with a 200 OK status as quickly as possible.
Offload heavy processing to background jobs or message queues.
Log and monitor webhook delivery attempts to aid in troubleshooting.

Last updated 17 days ago