Webhook Import via Halda App

Webhook Import lets an outside system (your CRM, marketing automation tool, or custom lead-scoring engine) push real-time funnel stage updates into Halda. Set it up once and your Halda funnel stays in sync with the source of truth automatically.

This guide walks through creating a webhook import, mapping your stages, activating it, and pointing your upstream system at the right endpoint.

Before you start

You'll need:

• A Halda account with admin access to Settings → Integrations
• A list of the stage names your upstream system uses (e.g. applied, qualified, enrolled)
• The Halda lead identifier (lead_profile_uid) of any lead you want to update — email and other identifiers are not accepted
• Someone on your team who can make HTTP requests from the upstream system

Step 1 — Create the webhook import

1. In Halda, go to Settings → Integrations.
2. Find Webhook Import in the list and click to create a new one.
3. Enter a Name that identifies the source — for example, "HubSpot — Marketing Funnel" or "Salesforce — Admissions." This is the label you'll see when managing the integration later.
4. Click Create.

You'll land on the configuration page for the webhook import you just created.

Step 2 — Copy your authentication token

On the configuration page you'll see an Authentication Token field. This is the secret your upstream system uses to prove its requests are legitimate.

• Click Copy Token to copy it to your clipboard.
• Store it somewhere your upstream system can read it (a secrets manager, an environment variable in your integration platform, etc.).
• If the token is ever exposed or you want to rotate it, click Regenerate. The old token stops working immediately.

Include this token in every request as a Bearer token in the Authorization header.

Step 3 — Copy the endpoint URL

Below the token, you'll find the API Endpoints section with two URLs:

• Single update — for webhooks that fire on individual stage changes. Send one update per request.
• Batch update (up to 100 records) — for nightly syncs or bulk operations. Send up to 100 updates in one request. Each record is evaluated individually, so one bad row won't reject the entire batch.

Click Copy URL next to whichever you'll use first. Most teams use the single update endpoint for live webhooks and the batch endpoint for backfills.

What each endpoint expects

• Single update: A POST or PATCH request with lead_profile_uid and funnel_stage in the body.
• Batch update: A POST or PATCH request with a records array — each item containing a lead_profile_uid and funnel_stage.

The response tells you whether each lead was updated, was already at the requested stage, or could not be matched.

Step 4 — Map your external stage names

This is the most important step. Your upstream system probably uses different stage names than Halda does — for example, your CRM might say qualified leadwhere Halda has application started. Mappings tell Halda how to translate.

In the Funnel Stage Mappings section:

1. Click Add Mapping.
2. Under External Stage Name, enter exactly what the upstream system will send — e.g. applied, enrolled, qualified.
3. Under Internal Funnel Stage, pick the matching Halda funnel stage from the dropdown.
4. Repeat for every stage you expect to receive.
5. Click Save Mappings when you're done.

A few things to know about how matching works:

• Mappings win first. If Halda sees a stage name it recognizes from your mappings, it uses that.
• If there's no explicit mapping, Halda falls back to matching against your Halda funnel stage titles directly.
• Matching is case-insensitive and tolerates small formatting differences. You don't need a mapping for every conceivable variation.

You can come back and edit mappings at any time. New mappings apply to all future requests immediately.

Step 5 — Activate the webhook import

New webhook imports are inactive by default so you can finish configuring before any traffic flows through.

When you're ready, click Activate at the bottom of the configuration page. The button toggles to Deactivate, which you can use any time you need to pause incoming updates — for example, during a migration or upstream outage. Deactivating preserves all your configuration, so reactivating is a single click.

Step 6 — Point your upstream system at Halda

In the upstream system (CRM, marketing platform, automation tool, custom script), configure an outbound webhook or scheduled job that:

1. Hits the endpoint URL you copied in Step 3.
2. Includes Authorization: Bearer <your token> in the headers.
3. Sends lead_profile_uid and funnel_stage in the request body (or a records array for batch).

Send a test request with a known lead and watch for a success: true response. Then check that lead in Halda — you should see the new stage reflected immediately, with the change recorded in the lead's funnel history.

What Halda handles automatically

Once active, you don't need to think about these — they just work:

• Skipped stages get backfilled. If a lead jumps from Inquiry straight to Application Complete, Halda fills in the in-between stages so reporting stays accurate.
• Backward moves are reconciled. If a lead moves back to an earlier stage, Halda archives the now-invalid future events so the audit log reflects reality.
• Duplicates are ignored. Sending the same stage twice is a no-op — no duplicate events, no errors.

Troubleshooting

• Lead profile not found — The lead_profile_uid doesn't exist in this account. Confirm you're using the Halda UID, not an email or external ID.
• Invalid funnel stage — The stage name doesn't match any mapping or Halda funnel stage. Add a mapping in Step 4.
• Authorization token required or Invalid or inactive webhook import token — The token is missing, wrong, or the webhook import is deactivated. Check the header and confirm the toggle at the bottom of the page reads Deactivate (meaning it's currently active).

Where to find it again

Anytime you need to edit mappings, regenerate the token, or activate or deactivate: Settings → Integrations → Webhook Import, then open the one you want to edit.