FAQs & Troubleshooting
      Back to home
      1. Canibuild Help Center
      2. FAQs & Troubleshooting

      How to use Webhooks in Canibuild

      This article explains how webhooks work within Canibuild & how they automatically send real-time data to external systems when key actions occur. Webhooks notify connected platforms instantly when important events happen in the application.

      Webhooks can track address look-ups, design placements, contact creation, document generation, quote status updates, LeadConvertor enquiries, payments, & login activity. Each event sends a structured payload with project, contact, & user information, enabling seamless integration with CRMs, analytics platforms, & third-party automation tools.

      Webhook events are grouped into the following categories:

      • PRO App Events (SiteCheck)

      • LeadConvertor Events

      • HubSpot Events

      What Are Webhooks In Canibuild?

      • Webhooks trigger automatically when specific actions occur in the Canibuild platform.
      • Each trigger sends a structured JSON payload to a configured endpoint so external systems can receive, interpret, & act on the data immediately.
      • These events provide context about the user, project, address, design, builder, & system state at the moment the action occurs.
      In software development, API stands for Application Programming Interface. 
      An API is a set of rules, protocols, and tools that allows different software applications to communicate and interact with each other without human intervention. It defines the methods and data formats that applications can use to request and exchange information. 

      CRM & Third-Party Integrations

      Webhook data can be mapped directly into external systems such as HubSpot, allowing:

      • Contact creation & updates.
      • Payment success tracking.
      • Lifecycle stage automation.
      • Revenue & attribution reporting.

      Below is a colour coded break down to help you understand what is happening in each JSON Payload.

      • 🟦 Event Metadata – what happened & when

      • 🟩 User Info – who performed the action

      • 🟨 Address / Project Info – where the action occurred

      • 🟪 Design / Document Info – what was worked on

      • 🟥 System / Status Info – state changes or outcomes

      PRO App Webhook Events

      Event: Address Look-up

      Trigger

      • Triggered when a user performs an address look-up in any way.
      • Using the search bar, right-clicking on the map, unlocking a deal, or any action that creates a new look-up.

      Functionality

      • Sends an event once an address look-up has occurred.

      What Happens

      • A webhook is fired as soon as the address look-up is created.
      • The payload contains address details, lookup identifiers, user information, & timestamps.
      • This event is commonly used to track early user intent & property interest.

      A user searches for or creates an address lookup in Canibuild (via search, map interaction, or deal unlock). This webhook records intent — it tells external systems “a user is now interested in this property” and creates a reference (lookup_id) that future actions can attach to.

      Sample Payload

      {
        🟦 "event": "address_lookup",
        🟦 "timestamp": "2025-06-05T12:34:56Z",

        🟩 "user_email": "user@canibuild.com",
        🟩 "ip": "103.186.68.230",

        🟨 "lookup_id": "LKP-123456",
        🟨 "deal_id": "DL-987654",
        🟨 "address": "41854 Calle Californios Lancaster, CA 93536, USA",
        🟨 "addressStreet": "41854 Calle Californios",
        🟨 "city": "Lancaster",
        🟨 "state": "CA",
        🟨 "zip": "93536",
        🟨 "country": "USA"
      }

      Event: Design Added

      Trigger

      • Triggered when a user places a design on a lot after completing an address look-up in the PRO app.

      Functionality

      • Sends an event once a design has been placed on the selected address.

      What Happens

      • The webhook links the selected design to the original address look-up.
      • Design name, build type, lookup link, & user details are included.
      • This event signals qualified design interest & progression in the workflow.

      After an address has been looked up, the user places a design on the lot. This webhook confirms active engagement — not just interest in land, but interest in a specific home design for that site.

      Sample Payload

      {
        🟦 "event": "design_added",
        🟦 "timestamp": "2025-06-05T12:35:00Z",

        🟩 "user_email": "user@canibuild.com",
        🟩 "ip": "103.186.68.230",

        🟨 "lookup_id": "13984",
        🟨 "deal_id": "DL-987654",
        🟨 "address": "Lot 426, Stage 4, Oakden Rise, SA 5086, Australia",
        🟨 "lookup_link": "https://app.canibuild.com/lookup/DL-987654",

        🟪 "design_name": "Windermere Street 12>12",
        🟪 "build_type": "house and land packages"
      }

      Event: Contact Added

      Trigger

      • Triggered when a user adds a contact in the CRM after placing a design.

      Functionality

      • Sends contact and project details once a contact is created.

      What Happens

      • Contact details such as name, email, phone number, billing address, & primary contact status are captured.
      • The contact is linked to the relevant lookup, design, & user.
      • This event supports CRM synchronisation & sales follow-up workflows.

      The user moves into the CRM stage and adds a contact against the lookup. This converts anonymous activity into a named lead, allowing sales teams and CRMs to take ownership of the opportunity.

      Sample Payload

      {
        🟦 "event": "contact_added",
        🟦 "timestamp": "2025-06-05T12:35:00Z",

        🟩 "user_email": "user@canibuild.com",
        🟩 "ip": "103.186.68.230",

        🟩 "contact_name": "John Smith",
        🟩 "contact_phonenumber": "+1 987-(654)-0091",
        🟩 "contact_email": "John987654@gmail.com",
        🟩 "contact_primary": "true/false",
        🟩 "contact_billingaddress": "380 Gibbs Ave, Newport, RI 02840, USA",

        🟨 "address": "380 Gibbs Ave, Newport, RI 02840, USA",
        🟨 "lookup_link": "https://app.canibuild.com/lookup/987654",

        🟪 "design_name": "Windermere Street 12>12",
        🟪 "build_type": "house and land packages"
      }

      Event: Document Generate Requested

      Trigger

      • Triggered when a user generates a document via the Generate option in the left panel.

      Functionality

      • Sends details of the generated document and associated project data.

      What Happens

      • A webhook is fired for every document type, including Quotes, Flyers, Site Plans, & custom documents.
      • The payload includes document type, contact details, address, design, build type, & lookup link.
      • This event tracks document demand & downstream engagement.

      The user actively requests a generated document (quote, flyer, site plan, etc.). This webhook signals commercial intent — the lead has moved from browsing to requesting formal material.

      Sample Payload

      {
        🟦 "event": "document_generate_requested",
        🟦 "timestamp": "2025-06-05T12:35:00Z",

        🟩 "user_email": "user@canibuild.com",
        🟩 "ip": "103.186.68.230",

        🟩 "contact_name": "John Smith",
        🟩 "contact_phonenumber": "+1 987-(654)-0031",
        🟩 "contact_email": "john@gmail.com",

        🟨 "address": "380 Gibbs Ave, Newport, RI 02840, USA",
        🟨 "lookup_link": "https://app.canibuild.com/lookup/987654",

        🟪 "document_type": "Quote / Flyer / Siteplan",
        🟪 "design_name": "Windermere Street 12>12",
        🟪 "build_type": "house and land packages"
      }

      Event: Quote Status Updated

      Trigger

      • Triggered when a generated quote changes status to signature requested or signature done.

      Functionality

      • Sends updated quote status and pricing details.

      What Happens

      • The webhook reports the new quote status along with sent date, signed date, total price, & quote link (if available).
      • Contact, address, design, & user context is included.
      • This event is critical for tracking sales progression & contract completion.

      A previously generated quote changes state — either sent for signature or fully signed.
      This webhook marks a critical sales milestone and is commonly used to:

      • trigger follow-ups

      • update CRM deal stages

      • notify sales or finance teams

      Sample Payload

      {
        🟦 "event": "quote_status_updated",
        🟦 "timestamp": "2025-06-05T12:35:00Z",

        🟩 "user_email": "user@canibuild.com",
        🟩 "contact_name": "John Smith",
        🟩 "contact_email": "John987654@gmail.com",

        🟨 "address": "380 Gibbs Ave, Newport, RI 02840, USA",
        🟨 "lookup_link": "https://app.canibuild.com/lookup/987654",

        🟪 "design_name": "Windermere Street 12>12",
        🟪 "build_type": "house and land packages",

        🟥 "quote_status": "signature_requested / signature_done",
        🟥 "quote_sent_date": "",
        🟥 "quote_signed_date": "",
        🟥 "quote_total_price": "",
        🟥 "quote_link": "Quote PDF link"
      }

      LeadConvertor Webhook Events

      Event: Enquire (Contact Form Submitted)

      • Payload (Design Found)
      • Payload (No Design Found – New LC)
      • Payload (Plan to Rebuild & Existing Owner Disabled)

      Trigger

      • Triggered when the contact form is submitted via the LeadConvertor widget.

      Functionality

      • Sends enquiry details including contact information, address, selected design, and tracking data.

      Effect

      • A new lead is logged & builders can be notified to follow up.

      What Happens

      Payload (Design Found)

      • A visitor submits the Canibuild enquiry form after finding a matching design.
      • This webhook captures lead intent, builder attribution, rebuild context, & marketing tracking, allowing builders or CRMs to immediately action the enquiry.

      Payload (No Design Found – New LC)

      • A visitor submits the Canibuild enquiry form after finding a matching design.
      • This webhook captures lead intent, builder attribution, rebuild context, & marketing tracking, allowing builders or CRMs to immediately action the enquiry.

       

      Payload (Plan to Rebuild & Existing Owner Disabled)

      • The LeadCapture configuration does not include rebuild ownership questions, so those values are intentionally null.
      • This webhook confirms config-driven payload behaviour.

      Sample Payload (Design Found)

      {
        🟦 "status": "complete",
        🟦 "date": "2025-02-06T03:46:29.785Z",
        🟦 "ip": "49.36.180.197",

        🟩 "firstname": "John",
        🟩 "lastname": "Doe",
        🟩 "email": "johndoe@gmail.com",
        🟩 "phone": "9012391230",

        🟨 "address": "44 W Altadena Dr, Altadena, CA 91001, USA",
        🟨 "addressStreet": "44 W Altadena Dr",
        🟨 "city": "Altadena",
        🟨 "state": "CA",
        🟨 "zip": "91001",
        🟨 "country": "USA",
        🟨 "lookupLink": "https://app.canibuild.com/lookup/12345",

        🟪 "designName": "Valencia",
        🟪 "message": "I'm interested in Valencia for my home rebuild...",
        🟪 "planToRebuild": "Yes",
        🟪 "existingOwner": "Yes",

        🟥 "builderId": 6,
        🟥 "builderName": "ACME Homes",
        🟥 "widgetReferenceName": "ACME Construction ",
        🟥 "idTenant": 1,
        🟥 "idLead": 462,
        🟥 "idWidgetConfig": 2,
        🟥 "book_consult": true
      }

      Sample Payload (No Design Found – New LC)

      {
        🟦 "status": "complete",
        🟦 "date": "2025-12-10T00:34:43.484Z",
        🟦 "ip": "49.43.224.225",

        🟩 "firstname": "John",
        🟩 "email": "Smith",
        🟩 "phone": "000000000",

        🟨 "address": "804 W Altadena Dr, Altadena, CA 91001, USA",
        🟨 "lookupLink": "https://web.nonprod.cloud.verumtek.com.au/lookup/80195",

        🟪 "message": "I couldn't find any matching designs...",
        🟪 "designName": "",
        🟪 "planToRebuild": "yes",
        🟪 "existingOwner": true,

        🟥 "widgetReferenceName": "ACME Construction",
        🟥 "idTenant": 528,
        🟥 "idLead": 1184,
        🟥 "idWidgetConfig": 122
      }

       Sample Payload (Plan to Rebuild & Existing Owner Disabled) 

      {
        🟦 "status": "complete",
        🟦 "date": "2025-12-10T00:42:13.887Z",

        🟩 "firstname": "John",
        🟩 "email": "John1234@gmail.com",

        🟨 "address": "840 W Altadena Dr, Altadena, CA 91001, USA",
        🟨 "lookupLink": "https://web.nonprod.cloud.verumtek.com.au/lookup/80199",

        🟪 "designName": "",
        🟪 "message": "I couldn't find any matching designs...",
        🟪 "planToRebuild": null,
        🟪 "existingOwner": null,

        🟥 "widgetReferenceName": "token usa",
        🟥 "idTenant": 528,
        🟥 "idLead": 1185,
        🟥 "idWidgetConfig": 122
      }

       
      Event: Address Look-up (Widget)

      Trigger

      • Triggered when a user looks up an address and places a design via the LeadConvertor.

      Functionality

      • Sends widget-based address and design activity.

      What Happens

      • A widget user looks up an address and places a design.
      • This event signals qualified design interest tied to a builder-branded widget.

      Sample Payload

      {
        🟦 "date": "2024-12-19T05:43:22.526Z",
        🟦 "ip": "103.186.68.230",

        🟨 "address": "41854 Calle Californios Lancaster, CA 93536, USA",
        🟨 "lookupLink": "https://app.canibuild.com/lookup/12345",

        🟪 "designName": "Asilo - Modern",
        🟪 "buildType": "House & Land",

        🟥 "builderId": 6,
        🟥 "builderName": "Test Builder 1",
        🟥 "widgetReferenceName": "Test Token 123",
        🟥 "idTenant": 1,
        🟥 "idWidgetConfig": 2
      }

      Event: Payment

      Trigger

      • Triggered when a payment is made via the Bottom CTA.

      Functionality

      • Sends payment confirmation or cancellation details.

      What Happens

      • A user completes (or cancels) a payment via the widget CTA.
      • This webhook confirms transaction success, linking revenue to leads, designs, & zones.

      {
        🟦 "status": "paid",
        🟦 "date": "2025-02-06T03:46:55.386Z",

        🟩 "userEmail": "johndoe@gmail.com",
        🟩 "userName": "John Doe",

        🟨 "address": "9 Bridgeview Cct, Bella Vista, NSW 2153, Australia",
        🟨 "lookupLink": "https://app.canibuild.com/lookup/12345",

        🟪 "serviceText": "Buy a Feasibility Study",
        🟪 "designName": "Design X",

        🟥 "amount": 10,
        🟥 "currency": "aud",
        🟥 "paymentIntentId": "pi_3QXcb1RBkrzbfvlU0GEDvlaR",
        🟥 "idLead": 1746,
        🟥 "idTenant": 1
      }

      Event: Login (Upcoming)

      Trigger

      • Triggered after a successful login via Google, OTP, One Tap Login, or other supported login methods.

      Functionality

      • Sends login session details with optional design and address information.

      What Happens

      • A user successfully logs in via Google, OTP, or widget-triggered actions.
      • This webhook links authentication behaviour with designs, lookups, & lead creation.

      {
        🟦 "userLoggedIn": true,
        🟦 "trigger": "add_to_favourites",

        🟩 "email": "dsmith@gmail.com",
        🟩 "name": "DaveSmith",
        🟩 "phone": "+109090909090",

        🟨 "address": "720 SOUTH 5TH TEXOMA TX 79086 USA",
        🟨 "lookupLink": "https://app.canibuild.com/lookup/1487441",

        🟪 "designName": "TestRandomHouse",

        🟥 "source": "login",
        🟥 "isNewLead": true,
        🟥 "device": "macOS",
        🟥 "idLead": 14530,
        🟥 "idTenant": 821
      }

      HubSpot Webhook Events

      Event: Enquire

      Trigger

      • Triggered when a LeadConvertor enquiry is submitted and sent to HubSpot.

      What Happens

      • A Canibuild enquiry is mapped into HubSpot contact properties, enabling CRM workflows.

      {
        🟩 "email": "john.doe@gmail.com",
        🟩 "properties": {
          "firstname": "John",
          "lastname": "Doe",
          "phone": "+1234567890",
          "address": "123 Main St",
          "city": "New York",
          "state": "NY",
          "zip": "10001",
          "country": "USA",
          "tracking_url": "utm_source=google.com"
        }
      }

      Event: Payment Success

      Trigger

      • Triggered when a payment is completed successfully.

      What Happens

      • A successful payment updates HubSpot with revenue, product, & deal context.

      {
        🟥 "properties": {
          "order_amount": 99.99,
          "hs_currency_code": "USD",
          "email": "john.doe@gmail.com",
          "service_availed": "Premium Subscription",
          "design_name": "Custom Design #123",
          "address": "123 Main St, New York, NY 10001"
        }
      }

      Event: Login

      Trigger

      • Triggered when a user logs in and HubSpot tracking is enabled

      What Happens

      • A login event is passed into HubSpot using existing contact identifiers, tying user authentication to lifecycle tracking.

      {
        🟦 "Lookup Link": "https://app.canibuild.com/lookup/1487441",

        🟩 "Client Name": "davesmith",
        🟩 "Client Email": "dsmith@gmail.com",
        🟩 "Client Phone": "+109090909090",

        🟨 "Address": "720 S 5th Texoma, Texhoma, Texas, 79086, USA",

        🟪 "Design Name": "Test - Random House",

        🟥 "Client Message": "undefined",