Developers

Send leads in and out with Zapier or a webhook

Post leads into Chalk from Zapier, Make or your own website form, and send every lead update out to an address you choose.

Updated By Adrian Gluchowski3 min read

On this page

Chalk has two connectors for this under Settings > Connectors > Build your own. Lead ingest takes leads in: your tool posts JSON to one address with a key. Zapier & webhooks sends every lead update out to an address you choose. In Zapier you use Webhooks by Zapier for both. Only the owner or an admin can set them up.

Send leads into Chalk

  1. Go to Settings > Connectors and open Lead ingest.
  2. If the API key box is empty, press Regenerate to make one. Press Copy.
  3. Copy the Endpoint. It ends in /api/ingest/lead.
  4. In Zapier, Make or your own code, send a POST with JSON to that endpoint, with the key in a header named X-Api-Key. Copy sample gives you a ready example to start from.
  5. Press Send a test lead to check it. This makes a real lead on your Funnel (Jane Smith), with the usual alert and owner text. Archive it afterwards.

The fields are:

FieldNotes
first_nameRequired
phone, emailAt least one is required. A phone must be a 10-digit US number
last_name, street1, city, state, postal_codeOptional
title, detailsWhat they want. The title shows on the Funnel card
sourceShows as the lead's source. Without it, Chalk writes "Website Estimator"
filesPhotos: a list of { filename, content_type, data }, data in base64. Or post multipart with a photos field

A good post answers 201 with the new request_id and client_id. A missing or wrong key answers 401. For leads from Facebook lead ads, add Meta's lead id too. See Connect Facebook lead ads to Chalk.

Leads that come in this way land exactly like a request from your website form: on the Funnel in New lead, attached to a repeat customer when the phone or email and name match, with the same app alert and owner text. See How leads get into Chalk.

Send lead updates out

  1. In Zapier, create a Zap that starts with Webhooks by Zapier, event Catch Hook, and copy the address it shows. Any address of your own that accepts a POST works too.
  2. In Chalk, go to Settings > Connectors and open Zapier & webhooks.
  3. Paste the address into Webhook address. It must start with https://.
  4. If you want, set a Signing secret (see below).
  5. Press Save and test. Chalk sends one test event so Zapier has fields to map.
  6. Build the rest of the Zap from that sample.

Chalk then posts one event each time one of these happens on a lead:

EventWhen
lead_createdA new lead arrives
assessment_bookedAn estimate visit is booked
quote_createdA quote is started
quote_sentThe quote is sent
quote_viewedThe customer opens the quote
changes_requestedThe customer asks for changes
job_createdThe work is booked in

Each post is JSON with event, at (the time), business (your shop's name), request (the lead's id, title and stage) and client (id, name, phone, email).

With a signing secret set, every post carries an X-Signature header: the HMAC-SHA256 of the body with your secret, in hex. Your side can check it to know the post really came from Chalk.

Good to know

  • The Lead ingest key only creates leads. It is not the same as a Chalk API key, and it cannot read or change anything else. Press Regenerate if it leaks; whatever used the old key stops working.
  • Keep the key out of anything public, like the code of a web page. Post from a server, Zapier or Make instead.
  • If a delivery out fails or takes longer than 4 seconds, Chalk tries again after 5 minutes and then after 30. After 3 failed tries it switches the connector off and sends you an alert, "Your Zapier link stopped". Press Save and test to turn it back on.
  • Quotes and jobs Chalk ties to a lead later, or that you tie with Tie to this lead, do not send events.
  • Payments, texts and other records are not sent out by this connector. For more than lead events, use a Chalk API key.