How to Use Alivo's Custom Inbound Webhook

A custom inbound webhook is a secure URL that lets another system push lead data into Alivo. When a form is filled, a CRM record is created, or an automation fires, that outside tool can send the contact's info to Alivo as a JSON payload (a structured block of data in a standard web format). Alivo creates the lead in your pipeline and can start a text conversation through your assigned agent. This guide walks through creating the webhook in Alivo, what to send in the request, and how to wire it up from Zapier, Make, or your own software.

What This Is (and What It Is Not)

This is an inbound webhook: data comes into Alivo from somewhere else. That is different from the Webhooks tab under Settings → Integrations, which sends events out of Alivo when something happens (like a new lead or a booked appointment). Inbound custom webhooks live under Lead Sources in the same Integrations area.

Good to know: Use a custom inbound webhook when Alivo does not have a native button for your lead source. If a native integration exists (Angi, Thumbtack, Google LSA, and others), that path is simpler. Reach for the custom webhook when you need to connect your own site, a niche tool, or anything you can route through Zapier or Make.

1. Create the Custom Lead Source in Alivo

Start inside Alivo. You need a lead source record before any outside system has somewhere to send data.

Open Lead Sources

Go to Settings → Integrations → Lead Sources. Click Add (or the add integration control on that page).

Add a Custom Integration

Choose Lead Source as the integration type, then select Custom from the list. You will see three things to fill in:

• Account ID. Click the refresh icon to generate a unique ID (a UUID, which is just a long random identifier). Copy this value. In your webhook payload it is sent as integration_id. Alivo uses it to know which account and lead source the lead belongs to.
• Description. Required. This becomes the lead source label in Alivo reporting (for example "Website contact form" or "Facebook leads via Zapier").
• Save. Create the integration before you configure anything on the outside system.

Connect an Agent

After saving, open the integration again to edit it. In the Agent dropdown (shown as "Campaign" in the settings screen), pick the agent you want handling these leads, usually Evan for digital follow-up. The agent must be Active (started on the Agents page) before Alivo will send automatic text replies. If no agent is linked, the lead still lands in your pipeline, but automatic follow-up will not start.

Keep in mind: The same contact will not be added to an agent conversation more than once per hour. That prevents duplicate texts when an outside system sends the same person twice in a short window.

2. The Webhook URL and Request Format

Every custom inbound lead uses the same Alivo endpoint. Your outside system sends an HTTP POST (a standard way for apps to push data to a URL) with a JSON body.

Production URL:

https://alivo-api-production.azurewebsites.net/integration/custom/lead/create/

Method: POST
Content-Type: application/json
Body: JSON object (see examples below)

A successful request returns HTTP 200 with a response like:

{
   "status":"success",
   "url":"https://app.alivo.ai/audience/..."
}

The url field links directly to the contact record in Alivo. If something is wrong (missing fields, invalid phone, unknown integration ID), you get a 400 response with an error message in the body.

3. Required and Optional Fields

Only three fields are required. Everything else helps Alivo qualify the lead and gives your agent more context.

4. Example Payloads

Minimal Example

This is the smallest valid payload. Use it when you only have a phone number and you have confirmed text opt-in.

{
   "integration_id":"a3f8c2d1-9b4e-4a1f-8c7d-2e5f6a7b8c9d",
   "audience_phone":"+12223334444",
   "audience_phone_opt_in":true
}

Full Example

This includes every optional field Alivo accepts on the custom inbound webhook. Send only the fields you actually have.

{
   "integration_id":"a3f8c2d1-9b4e-4a1f-8c7d-2e5f6a7b8c9d",
   "audience_full_name":"John Doe",
   "audience_first_name":"John",
   "audience_last_name":"Doe",
   "audience_phone":"+12223334444",
   "audience_email":"john.doe@email.com",
   "audience_company":"Doe Roofing LLC",
   "audience_website":"www.doeroofing.com",
   "audience_phone_opt_in":true,
   "audience_email_opt_in":true,
   "audience_address":"123 Main St",
   "audience_city":"Anytown",
   "audience_state":"CA",
   "audience_zip_code":"12345",
   "audience_notes":"Interested in a roof inspection after recent hail",
   "audience_ai_context":"High-intent lead from website contact form",
   "audience_source":"Website contact form",
   "external_id_name":"HubSpot Contact ID",
   "external_id_id":"crm-contact-12345",
   "audience_utm_source":"google",
   "audience_utm_medium":"cpc",
   "audience_utm_campaign":"spring-roofing",
   "audience_utm_term":"roof repair",
   "audience_utm_content":"ad-variant-a"
}

5. Configure the Outside System

Once the lead source exists in Alivo, set up your form, CRM, or automation tool to POST to the webhook URL whenever a new lead appears. The exact screens differ by platform, but the pattern is the same everywhere.

Zapier or Make

1. Create a new Zap or scenario.
2. Set the trigger to whatever creates the lead (new Facebook Lead, new HubSpot contact, new form submission, new spreadsheet row, and so on).
3. Add a Webhooks action and choose POST.
4. Paste the Alivo production URL as the request URL.
5. Set the payload type to JSON.
6. Map your trigger fields into the Alivo field names. At minimum map phone to audience_phone, set integration_id to your Account ID, and set audience_phone_opt_in to true.
7. Test the Zap or scenario with your own phone number, then confirm the contact appears in Alivo.

Your Own Website Form or Backend

If you control the code that handles form submissions, send a POST request from your server when the form is saved. Do not expose the webhook from browser-side JavaScript on a public page if you can avoid it. Server-side is more reliable and keeps your integration setup cleaner.

Example using curl from a terminal (useful for a quick test):

curl -X POST \   https://alivo-api-production.azurewebsites.net/integration/custom/lead/create/ \   -H "Content-Type: application/json" \   -d '{     "integration_id": "a3f8c2d1-9b4e-4a1f-8c7d-2e5f6a7b8c9d",     "audience_phone": "+12223334444",     "audience_phone_opt_in": true,     "audience_first_name": "Test",     "audience_last_name": "Lead"   }'

After You Connect It

Send a test lead using your own phone number. Then check Alivo:

• The contact should appear in your pipeline with the source label from your integration description (or from audience_source if you sent one).
• If an active agent is linked and the contact opted in to texts, Evan should send the first message within about a minute.
• If something fails, open the contact in Alivo and check integration logs, or reach out to support with the time of your test.

Rule of thumb: Get the minimal payload working first (integration ID, phone, opt-in). Add name, email, address, and notes once you see the lead land in Alivo. Layering fields in one at a time makes troubleshooting much easier.

Common Questions

Where Do I Find My integration_id?
It is the Account ID on your Custom lead source in Settings → Integrations → Lead Sources. Generate it with the refresh icon when you create the integration, and copy it from the edit screen anytime.

Why Did My Lead Show Up but No Text Go Out?
Check three things: an agent is selected on the integration, that agent is Active on the Agents page, and audience_phone_opt_in was sent as true. Also confirm you have not sent the same phone number again within the last hour.

Can I Send Leads Without a Phone Number?
No. audience_phone is required. The custom inbound webhook is built for leads you can text or call.

Is This the Same as Outbound Webhooks?
No. Inbound custom webhooks (this article) bring leads into Alivo. Outbound webhooks under Settings → Integrations → Webhooks notify your other systems when something happens inside Alivo.

The custom inbound webhook is your catch-all path for leads that do not have a native Alivo integration. Create the Custom lead source, copy your Account ID, POST JSON to the production URL, link an active agent, and test with your own number before you flip it on for real traffic.

Still have a question this didn't answer? Reach out to our support team support@alivo.ai and we'll be glad to help.