> For the complete documentation index, see [llms.txt](https://docs.spara.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.spara.com/guides/integration-guides/webhook-web-api-or-workflow-api-step.md).

# Webhook, Web API, or Workflow API Step?

Choose the right way to move data between Spara and your other systems: webhooks, the Web API, or a Workflow API step.

Outside of Spara's native CRM integrations, there are three ways to move data between Spara and your other systems. They look similar — all three send JSON over HTTPS — but they solve different problems, and picking the wrong one usually shows up later as missing data or a broken sync.

Use this page to pick the right one. For setup details, see [https://docs.spara.com/developers/spara-api/webhooks](https://docs.spara.com/developers/spara-api/webhooks "mention"), [https://docs.spara.com/developers/spara-api/web-api](https://docs.spara.com/developers/spara-api/web-api "mention"), and the [https://docs.spara.com/agents/workflows/steps/api](https://docs.spara.com/agents/workflows/steps/api "mention").

## The short version

* **Webhook** — Spara pushes every matching event to you, forever. Best for keeping an external system continuously in sync.
* **Web API** — you call Spara when you want data or want Spara to do something. Best for on-demand lookups, backfills, and writing into Spara.
* **Workflow API step** — Spara calls your system once per lead, with a payload you design. Best for a one-time enrichment or handoff that needs to authenticate to a third party.

## Side-by-side

<table data-full-width="true"><thead><tr><th></th><th>Webhook</th><th>Web API</th><th>Workflow API step</th></tr></thead><tbody><tr><td><strong>Who starts it?</strong></td><td>Spara</td><td>You</td><td>Spara</td></tr><tr><td><strong>How often does it fire?</strong></td><td>Every time a subscribed event happens, for the life of the lead</td><td>Whenever you make a call</td><td>Once per lead, per workflow</td></tr><tr><td><strong>Request methods</strong></td><td><code>POST</code> only</td><td><code>GET</code>, <code>POST</code>, <code>PATCH</code></td><td><code>GET</code>, <code>POST</code>, <code>PUT</code></td></tr><tr><td><strong>Payload</strong></td><td>Fixed — the full lead object every time</td><td>Reads return the full lead object; writes send only the fields you're changing</td><td>Custom — you build the body field by field</td></tr><tr><td><strong>Can authenticate to a third party?</strong></td><td>No</td><td>Not applicable — you're the caller</td><td>Yes, using an encrypted secret</td></tr><tr><td><strong>Can write back into Spara?</strong></td><td>No — outbound only</td><td>Yes</td><td>Yes, via field extraction</td></tr><tr><td><strong>Needs an endpoint you host?</strong></td><td>Yes</td><td>No</td><td>Yes</td></tr><tr><td><strong>If it fails</strong></td><td>Two retries, then the delivery is dropped. No failure log in the Platform.</td><td>You get the error response back and decide whether to retry.</td><td>The lead's workflow run ends at that step. Nothing downstream runs, there is no retry, and the lead cannot re-enter the workflow. The failure is visible in the workflow logs.</td></tr><tr><td><strong>Limits</strong></td><td>20 deliveries per lead per minute; 10-second response timeout</td><td>10 requests per API key per minute; 1,000 leads per page</td><td>Only reaches leads active within the last year</td></tr></tbody></table>

## When to use each

### Use a webhook when

You need a running record of everything that happens to a lead, as it happens, for as long as the lead exists. A webhook is the only option that keeps firing indefinitely — the Workflow API step fires once per lead, and the Web API's rate limit makes frequent polling impractical.

Typical uses: mirroring every conversation into a data warehouse, feeding an enrichment tool, or pushing call outcomes into a lifecycle marketing platform.

### Use the Web API when

You need Spara's current state on demand, need to backfill history, or need Spara to take an action. The Web API is the only option that lets you make Spara do something — create a lead, update a lead, or place an outgoing call.

Typical uses: looking up a lead when a rep opens a record, backfilling leads created before you set up a webhook, or triggering an outgoing call from your own system.

### Use a Workflow API step when

You need a one-time, custom-shaped call per lead — especially one that must authenticate to a third party or write its result back onto the lead. It is the only option with a body you design yourself and the only one that can send a stored credential.

Typical uses: enriching a lead from a third-party data provider, creating a record in another system when a lead qualifies, or scoring a lead through an external model.

## Where webhooks fall short

Webhooks are deliberately simple: one fixed payload, one direction, every subscribed event. That simplicity is what makes them reliable, but it leaves real gaps. Each gap below has a workaround — with its own trade-off.

<table data-full-width="true"><thead><tr><th>Webhook limitation</th><th>Alternative</th><th>Trade-off of the alternative</th></tr></thead><tbody><tr><td>Cannot fire on one specific field changing — you get every subscribed event and filter on your side</td><td>A workflow with a Condition step followed by an API step</td><td>Fires once per lead, ever. You'd catch the first time the field changes, never again.</td></tr><tr><td>Cannot authenticate to a third party — the only credential sent is your own Spara API key</td><td>Workflow API step with a stored secret (bearer token or custom header)</td><td>Fires once per lead. The secret is static, so tokens that rotate frequently must be refreshed by hand.</td></tr><tr><td>No events for meeting scheduled, email opened, link clicked, form submitted, or unsubscribed</td><td>Workflow triggers cover all of these; follow the trigger with an API step</td><td>Fires once per lead — usually fine for these one-time moments.</td></tr><tr><td>Outbound only — a webhook can never write back into Spara</td><td>Web API, or a Workflow API step with field extraction</td><td>Web API is capped at 10 requests per key per minute. The API step runs once per lead.</td></tr><tr><td>Fixed payload — every delivery includes the full lead, including the entire message history, so payloads grow over the life of a conversation</td><td>Workflow API step with a hand-built body</td><td>You maintain the field list in every step, and a missing field can end the lead's run.</td></tr><tr><td>Forward-only — a webhook never covers leads created before you turned it on</td><td>Web API <code>/leads/search</code> to backfill</td><td>10 requests per key per minute, 1,000 leads per page.</td></tr><tr><td>No failure visibility in the Platform — a dropped delivery is silent</td><td>The Web API returns a response you can act on; the Workflow API step logs failures in the workflow's run history</td><td>Neither gives you the continuous stream a webhook does.</td></tr></tbody></table>

{% hint style="info" %}
These are not exclusive choices. A common pattern is a webhook for the continuous stream, plus a periodic Web API `/leads/search` sweep to reconcile anything a dropped delivery missed.
{% endhint %}

## Setting up a webhook

{% stepper %}
{% step %}

### Open API & Webhooks

Go to [**Settings > API & Webhooks**](https://app.spara.co/settings/api-webhooks). You need permission to edit integration and webhook settings.
{% endstep %}

{% step %}

### Create an API key

Select **Create API Key**. At least one API key must exist before outbound webhooks can be enabled. Spara sends this key in the `X-API-Key` header of every delivery so your endpoint can verify the request came from Spara.
{% endstep %}

{% step %}

### Add the webhook

Select **Add Webhook** and enter your `HTTPS` endpoint URL. Plain `HTTP` endpoints are rejected.
{% endstep %}

{% step %}

### Choose events

Select which of the eight events should fire to this endpoint. You can add more than one webhook, each with its own URL and its own set of events, to route different events to different destinations.
{% endstep %}

{% step %}

### Test it

Use the **Test** button to send a sample payload and confirm your endpoint accepts it.
{% endstep %}
{% endstepper %}

## FAQ

### Can I use more than one of these at once?

Yes, and most accounts do. Webhooks, the Web API, and Workflow API steps are independent of each other.

### Why did my lead only hit the API step once?

A lead enters a given workflow once. If the API step failed on that run, the run ended there and the lead will not re-enter. Check the workflow's run history to see the failure.

### My webhook endpoint was down for an hour. Can I replay what I missed?

Not directly — failed deliveries are dropped after two retries. Use the Web API's `/leads/search` endpoint with the `last_activity_from` parameter to pull everything that changed during the outage.

### Should I use webhooks to write back to my CRM?

Not if Spara already has a native integration with that CRM. Running both against the same records causes data conflicts. See [https://docs.spara.com/developers/spara-api/webhooks](https://docs.spara.com/developers/spara-api/webhooks "mention") for details.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.spara.com/guides/integration-guides/webhook-web-api-or-workflow-api-step.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.