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/web-api, and the https://docs.spara.com/agents/workflows/steps/api.

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

	Webhook	Web API	Workflow API step
Who starts it?	Spara	You	Spara
How often does it fire?	Every time a subscribed event happens, for the life of the lead	Whenever you make a call	Once per lead, per workflow
Request methods	POST only	GET, POST, PATCH	GET, POST, PUT
Payload	Fixed — the full lead object every time	Reads return the full lead object; writes send only the fields you're changing	Custom — you build the body field by field
Can authenticate to a third party?	No	Not applicable — you're the caller	Yes, using an encrypted secret
Can write back into Spara?	No — outbound only	Yes	Yes, via field extraction
Needs an endpoint you host?	Yes	No	Yes
If it fails	Two retries, then the delivery is dropped. No failure log in the Platform.	You get the error response back and decide whether to retry.	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.
Limits	20 deliveries per lead per minute; 10-second response timeout	10 requests per API key per minute; 1,000 leads per page	Only reaches leads active within the last year

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.

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

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.

Setting up a webhook

1

Open API & Webhooks

Go to Settings > API & Webhooks. You need permission to edit integration and webhook settings.

2

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.

3

Add the webhook

Select Add Webhook and enter your HTTPS endpoint URL. Plain HTTP endpoints are rejected.

4

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.

5

Test it

Use the Test button to send a sample payload and confirm your endpoint accepts it.

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 for details.