Inbound webhooks

Direction

In

Sign-in

None: the URL is the secret

Time to set up

About fifteen minutes

What this does

The Inbound Webhook trigger gives a workflow its own URL on smallbusinesschatbot.com. Each POST to that URL starts a run of the workflow, and the request's data becomes the run's trigger data. Any tool that can send a webhook can use it: a website form, a form builder, a Zap, your job software or your own code.

Before you start

• The other tool's setting for sending a webhook, open in another tab.
• A first workflow to build on: Your first workflow.

Add the trigger and copy the URL

1. Add the trigger

   In the app, open Workflows, open or create a workflow, and add the Inbound Webhook trigger.

2. Copy the URL

   Click the trigger. Under Inbound endpoint, Webhook URL shows https://smallbusinesschatbot.com/workflow/webhooks/ followed by a long random ID. Click Copy URL.

   

3. Save and publish

   Switch Status from Draft to Published, then click Save workflow. The URL starts runs only while the workflow is published.

Register the webhook in the other tool

In the other tool, paste the URL where it asks for a webhook URL, and pick POST if it asks for a method. It can send JSON, form fields or plain text. To send a test from a terminal instead:

curl -X POST https://smallbusinesschatbot.com/workflow/webhooks/YOUR-ENDPOINT-ID \
  -H "Content-Type: application/json" \
  -d '{"customer": {"name": "Jordan", "email": "[email protected]", "phone": "+15555550123"}, "form": {"message": "Quote for a new water heater"}}'

The reply carries execution_id, workflow_id and trigger_node_id, so the sending tool can log the run.

Capture a sample request

1. Send one request

   Send a test from the other tool, or the test request above.

2. Fetch it

   In the trigger, next to Sample requests, click Fetch sample requests. The request shows with the time it arrived and its body. The trigger keeps the last 20.

   

3. Mark your reference

   Click Use latest sample. Its ID goes into Mapping reference, a note of which sample your rules follow.

Map the fields

Without mapping rules, the whole request is the trigger data. With rules, the trigger data holds only the fields you map, and the original request stays available as trigger_raw.

1. Add a rule per field

   In the trigger, under Mapping rules, add a rule for each field you need. Source path is where the value sits in the request. Target path is the name your workflow uses. Default value fills in when the field is missing.

   

2. Map the person

   Map the person's details to contact.email, contact.phone and contact.first_name. The run is then tied to that contact, so a Remove From Cadence step can find and stop it.

The rules for the test request:

Paths use dots, and list positions are numbers. A request whose body is a JSON list arrives as value, so its first item is value.0.

To save the person as a CRM contact, add an Upsert Contact step after the trigger.

Test it

1. Send a real request

   With the workflow published, send a request from the other tool.

2. Check the run

   In Workflows, switch from Editor to Executions. The new run shows with its status. Open it to see each step's input and output.

   

What it does

• Starts one run per request while the workflow is published.
• Accepts POST requests with JSON, form fields (URL-encoded or multipart) or plain text. Plain text that holds JSON is read as JSON.
• Skips repeats. A request with the same Idempotency-Key or X-Idempotency-Key header as an earlier one returns that run's ID and starts nothing new.
• Gives each workflow its own URL. A duplicated workflow gets a new one.
• Uses the URL as the secret: anyone who has it can start the workflow, so keep it private. If it leaks, click Regenerate URL and save; the old URL stops working.

If something goes wrong