Webhook & API

Spara's Webhooks & API support completely customizable configurations.

The Spara platform offers powerful integration capabilities through both outbound webhooks and a suite of external API endpoints. 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.

Important: Spara does not support using webhooks/API AND a native integration, as this may result in data conflicts or unexpected behavior.

For example, Spara does not support using both webhooks and native Salesforce integration together.

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".

Webhooks

Spara supports outbound webhooks to enable real-time notifications of lead’s events. Webhooks allow you to automate workflows, synchronize data with external systems, and respond to important updates as they happen. Each webhook is delivered as a POST request to a customer-defined endpoint.

Supported Events

Spara currently supports the following webhook events:

lead.created - Triggered when a new lead is created
lead.facts_updated - Triggered when a fact is captured or has been updated

Please note that lead.facts_updated will not be triggered when facts 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 facts 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-06-10T12:00:01Z",
  "object": "lead",
  "id": "ABC12345",
  "created_at": "2025-06-09T12:00:00Z",
  "updated_at": "2025-06-09T15:15:00Z",
  "data": {
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Doe",
    "employee_count": 50
  },
}


// lead.facts_updated
{
  "event": "lead.facts_updated",
  "timestamp": "2025-06-10T12:00:01Z",
  "object": "lead",
  "id": "ABC12345",
  "created_at": "2025-06-09T12:00:00Z",
  "updated_at": "2025-06-09T15:15:00Z",
  "data": {
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Doe",
    "employee_count": 50
  },
}

Security

To ensure secure transmission, all webhook payloads must include one of the customer’s 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.

API

Spara provides a collection of external API endpoints to search and manage lead-related data. These APIs support deeper integration by enabling your systems to enrich lead context, maintain user information, and influence the behavior of our AI engine. This allows for greater customization and tighter alignment between your internal workflows and Spara’s capabilities.

All API interactions must be made over HTTPS to ensure secure and reliable communication.

Base URL

The base URL for all API requests is: https://api.spara.co/v1/

Authentication

All requests to the API must be authenticated using a Bearer Token in the Authorization header. Each customer can generate one or more API Keys via the user dashboard.

Header Example:

Authorization: Bearer YOUR_API_KEY

Error Responses

400 Bad Request: The request body is malformed JSON or contains invalid data for the metadata fields (e.g., wrong data type). The response body will provide details on the specific error.
401 Unauthorized: Missing or invalid API key.
403 Forbidden: API key does not have access to the specified lead.
404 Not Found: Lead with the provided id does not exist.
422 Unprocessable Entity: The request was well-formed, but semantic validation failed (e.g., attempting to set a field to a value that is logically impossible or not allowed, attempting to update read-only fields (e.g., ip_address)).
429 Too Many Requests: The number of requests has exceeded the rate limits.

Resource: Leads

The primary resource for this API is leads.

Search Leads (GET)

This endpoint allows you to search for leads by their email address. The response will include a unique identifier (id) for each lead, and all known facts about the lead. Zero (no lead found), one (only one lead found), or multiple leads (if there are multiple leads with the same email address) could be returned from this endpoint.

Endpoint: /leads/search

Method: GET

Description: Retrieves the full details of the leads that match the search criteria, including their current facts.

Query Parameters:

email (string, required): Email for the lead you wish to retrieve (case insensitive)

Example Request:

GET https://api.spara.co/v1/leads/[email protected]
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json


Example Success Response (HTTP 200 OK):

{
  "object": "list",
  "data": [
    {
      "object": "lead",
      "id": "ABC12345",
      "created_at": "2025-06-09T12:00:00Z",
      "updated_at": "2025-06-09T15:15:00Z",
      "data": {
        "email": "[email protected]",
        "first_name": "Jane",
        "last_name": "Doe",
        "employee_count": 50,
        "is_customer": false
      }
    }
  ]
}

Get Lead (GET)

This endpoint allows you to retrieve the current state of the lead’s facts. This is useful for understanding the existing data before performing an update.

Endpoint: /leads/{id}

Method: GET

Description: Retrieves the full details of a specific lead, including their current facts.

Path Parameters:

id (string, required): The unique identifier for the lead you wish to retrieve.

Example Request:

GET https://api.spara.co/v1/leads/ABC12345
Authorization: Bearer YOUR_API_KEY


Example Success Response (HTTP 200 OK):

{
  "object": "lead",
  "id": "ABC12345",
  "created_at": "2025-06-09T12:00:00Z",
  "updated_at": "2025-06-09T15:15:00Z",
  "data": {
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Doe",
    "employee_count": 50,
    "is_customer": false
}

Update Lead (PATCH)

This endpoint allows you to enrich the lead by providing pre-existing facts that you may have collected externally (e.g., from your CRM).

Endpoint: /leads/{id}

Method: PATCH

Description: Update information on the lead

Path Parameters:

id (string, required): The unique identifier for the lead you wish to update.

Content-Type: application/json

Body: A JSON object containing the fields you wish to update.

Example Request:

PATCH https://api.spara.co/v1/leads/ABC12345
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json


{
  "first_name": "Jane",
  "last_name": "Doe"
}

A success response will return 200 without any additional data.

Rate Limiting

To ensure fair usage and system stability, API requests are subject to rate limits. If you exceed the allocated rate limits, your requests will be temporarily blocked, and you will receive an HTTP 429 Too Many Requests status code.

Last updated 1 day ago