Hoowla Webhooks

Hoowla can make a HTTP POST request to a url provided when certain events occur. These events include when quotes are raised and when they are instructed. As well as actions run within Hoowla cases.

Retries
Parameters
Securing Webhooks
Quotes
Cases
Help

Retries

Once an action is performed you can expect to received the webhook within a minute, all being well.

When sending the webhook it will be marked as successful if a response code between 200-299 is received. Also, if the response back is returned as 406 it will be marked as not acceptable and rejected.

There is a timeout on the http request of 20 seconds, so a response over this time will be considered to have a status code of 0 (and be retried).

Anything other than the situations above and the webhook will be retried as follows:

Attempts 1-3: wait 10 minutes
Attempt 4: 1 hour
Attempt 5: 4 hours
Attempt 6: 12 hours
Attempt 6+: Rejected

Parameters

Listed below are all the fields sent in the webhook request, sent as application/x-www-form-urlencoded.

Name	Type	Desc
timestamp	int	the current unix timestamp in utc (number of seconds since 01/01/1970) generated when sending a request.
signature	string	the request signature used to verify authenticity in hexadecimal HMAC form and generated by the SHA256 algorithm.
id	string	a unique id for this payload, so subsequent attempts after failure will have same id. It's not tied to the quote, but to the event.
type	string	the type of hook: `quote` for a new quote raised `instruct` for when an existing quote has been instructed `rule_run` for a case rule payload `person_added` for a new person added webhook `note_added` for a new note added webhook
payload	string	a json string holding the relevant data, more info shown below.

Along with the body, HTTP Headers will be included:

`User-Agent` - our defined user agent of the webhook sender.
`X-Env` - will have a value of `production` or `test` depending on what environment the HTTP request was sent from.

Securing Webhooks

To verify that the message originated from Hoowla you will need to:

Concatenate the timestamp and the payload string
Encode the resulting string with HMAC SHA256 and by using your api key as the key
Compare the resulting string with signature field sent across and check it's not an old request

Example PHP Code:

<?php

// Step 1 & 2: Concatinate and Generate Hash
$both = $_POST['timestamp'] . $_POST['payload'];
$gen = hash_hmac('sha256', $both, '{ YOUR API KEY }');

// Step 3: Compare Hash to Signature and verify that the request is recent
$isValid = (
    hash_equals($gen, $_POST['signature'])
    && $_POST['timestamp'] > strtotime('-7 days')
);

?>

Quotes

Quote Raised Payload

Below is an example payload for a purchase quote raised.

{
  "clients": [
    {
      "person_id": 12345,
      "person_title": "Mr.",
      "person_fname": "Frank",
      "person_lname": "Curtis",
      "person_email": "frank@hoowla.com",
      "person_dob": "2020-01-01",
      "person_ni": "NI123456",
      "person_source": "Webhook Example",
      "address_line1": "Buckingham Palace",
      "address_line2": "",
      "address_city": "LONDON",
      "address_county": "",
      "address_postcode": "SW1A 1AA",
      "phone_numbers": [
        "01234 567 890",
        "+44 1234 567 890"
      ]
    }
  ],
  "quotes": [
    {
      "id": 12345678,
      "type": 1,
      "line1": "Buckingham Palace",
      "line2": "",
      "city": "LONDON",
      "county": "London",
      "postcode": "SW1A 1AA",
      "value": 130000,
      "people": 1,
      "holding": 2,
      "title": "DN100",
      "mortgaged": true,
      "unregistered": false,
      "shared_ownership": false,
      "new_build": false,
      "help_to_buy_equity_loan": false,
      "help_to_buy_isa": false,
      "buy_to_let": false,
      "first_time_buyer": true,
      "right_to_buy": false,
      "islamic_mortgage": false,
      "auction\/repossession": false,
      "self_build": false,
      "gifted_deposit": false,
      "share_of_freehold": false,
      "flat_or_apartment": false,
      "equity_release_advice": false,
      "lifetime_isa": false,
      "non_uk_resident": false,
      "client_is_company": false,
      "land_reg_has_run": true,
      "custom": [
        "my_test_custom_situation"
      ],
      "region": "england",
      "expiry": "2020-12-01 00:00:00",
      "supplements": [
        {
          "name": "Leasehold Fee",
          "fee": "150.00"
        },
        {
          "name": "VAT at 20%",
          "fee": "135.00"
        }
      ],
      "disbursements": [
        {
          "name": "ID Verification fee (per person)",
          "fee": "3.70"
        },
        {
          "name": "Search Pack (approx)",
          "fee": "199.00"
        },
        {
          "name": "Land Registry Fees",
          "fee": "95.00"
        },
        {
          "name": "Stamp Duty (SDLT)",
          "fee": "100.00"
        }
      ],
      "total_legal_fee_ex": "525.00",
      "total_legal_fee_inc": "630.00",
      "total_ex": "675.00",
      "total_inc": "1207.70"
    }
  ]
}

All Quotes:

Name	Type	Desc
id	int	the quote's unique id, this can be used later to link quotes raised to quotes instructed
type	int	the quote type: 1 = purchase, 2 = sale, 4 = remortgage, 8 = transfer of equity
line1	string	line 1 of the property address
line2	string	line 2 of the property address
city	string	town/city of the property
county	string	the property's county
postcode	string	the property's postcode
value	float	the property value
people	int	number of people involved in the quote - certain supplements and disbursements will be per person
holding	int	the tenure: 1 = freehold 2 = leasehold
title	string	the land registry title number (if the check was made)
mortgaged	bool	if the property is or will be using a mortgage
custom	array	this will list any 'activated' custom situations on the quote
region	string	the country the property is within, options include: england scotland wales nireland
expiry	string	when the quote is due to expire, in YYYY-MM-DD HH-MM-SS format
supplements	array	a list of supplements for the quote, with the fee listed ex-vat
disbursements	array	a list of disbursements for the quote, with the fee listed inc-vat
total_legal_fee_ex	string	the legal fee for the quote, as an ex-vat price
total_legal_fee_inc	string	the legal fee for the quote, as an inc-vat price
total_ex	string	the quote's total price, as an ex-vat value (= supplements (except vat row) + disbursements + legal fee ex vat)
total_inc	string	the quote's total price, as an inc-vat value (= supplements (including vat row) + disbursements + legal fee ex vat)

Purchase Extras:

Name	Type	Desc
unregistered	bool	if the property is not registered with the land registry
shared_ownership	bool	if the property purchase will be a shared ownership
new_build	bool	if the property is a new build
help_to_buy_equity_loan	bool	if the purchase is using a help to buy loan
help_to_buy_isa	bool	if the purchase is using a help to buy ISA
buy_to_let	bool	if the property is being purchased to let out (or is used as a 2nd home)
first_time_buyer	bool	if the purchaser has never purchased a property before
right_to_buy	bool	if the purchaser is under the right to buy scheme
islamic_mortgage	bool	if the purchaser is using an islamic mortgage
auction/repossession	bool	is being bought through an auction
self_build	bool	is a self build property
gifted_deposit	bool	if the deposit given was a gift to the client
share_of_freehold	bool	if the purchase is a share of a freehold
flat_or_apartment	bool	if this property is a flat or apartment
equity_release_advice	bool	whether equity release advice is offered
lifetime_isa	bool	is a Lifetime ISA is included in the quote
non_uk_resident	bool	if the client is a non-uk resident (will change SDLT calculations)
client_is_company	bool	if the client purchasing the residential property is a company (will change SDLT calculations)

Sale Extras:

Name	Type	Desc
unregistered	bool	if the property is not registered with the land registry
shared_ownership	bool	if the property is part of a shared ownership
help_to_buy_equity_loan	bool	if the sale involves a help to buy loan
share_of_freehold	bool	if the sale involves a share of a freehold
flat_or_apartment	bool	if this property is a flat or apartment
client_is_company	bool	if the client selling the property is a company

Quote Instructed Payload

Below is an example payload for a quote which has been instructed.

{
  "id": 1234,
  "case_id": 5678,
  "created_at": "2026-01-01 00:00:00"
}

Name	Type	Desc
id	int	the quote's unique id, this can be used to link to the original quote
case_id	int	if there is a case linked to this quote then the case id will be included, otherwise it will be null
created_at	string	when the instruction occurred in Europe/London timezone (GMT/BST)

Quote Edit Payload

Quote edit payloads are near identical to Quote Raised payloads and are structured as such. These webhooks are fired when someone edits a quote, even if nothing is changed.

Key differences:

The quote type will be quote_edited
Only values which can be edited, will be sent.
Only one quote will be sent. Users will need to edit Purchase and Sale quotes separately for this webhook to be sent for both.

{
  "clients": [
    {
      "person_id": 1234,
      "person_title": "",
      "person_fname": "John",
      "person_lname": "Doe",
      "person_email": "john.doe@example.com",
      "person_dob": "2021-11-24",
      "person_ni": "",
      "person_source": "",
      "address_line1": "32",
      "address_line2": "Example Lane",
      "address_city": "Exampleton",
      "address_county": "Yorkshire",
      "address_postcode": "DY5 3EH",
      "phone_numbers": [
        "00000 2000000"
      ]
    }
  ],
  "quotes": [
    {
      "id": 375710,
      "type": 2,
      "line1": "Example Lane",
      "line2": "",
      "city": "",
      "county": "",
      "postcode": "EXAM 8LE",
      "value": "200,000.00",
      "people": 2,
      "leasehold": false,
      "mortgaged": true,
      "unregistered": false,
      "shared_ownership": false,
      "holding": "",
      "title": "",
      "region": "england",
      "expiry": "2024-10-22 14:30:15",
      "supplements": [
        {
          "name": "Mortgage Fee",
          "fee": "125.00"
        },
        {
          "name": "Repayment of Mortgage",
          "fee": "50.00"
        },
        {
          "name": "VAT at 20%",
          "fee": "140.00"
        }
      ],
      "disbursements": [
        {
          "name": "ID Verification fee (per person)",
          "fee": "3.70"
        },
        {
          "name": "OCEs (Title & Plan)",
          "fee": "8.00"
        },
        {
          "name": "Telegraphic Transfer",
          "fee": "33.00"
        },
        {
          "name": "office copies",
          "fee": "6.00"
        }
      ],
      "total_legal_fee_ex": "525.00",
      "total_legal_fee_inc": "630.00",
      "total_ex": "750.70",
      "total_inc": "890.70"
    }
  ]
}

Please refer to the table for Quote Raised which details the data types. In Quote Edit, the types which have changed are as follows:

Name	Type	Desc
value	string	the property value
consideration	string	the total monetary value exchanged for the property

Testing Quote Webhooks

When creating a webhook within Hoowla, there's an option to send a test request with dummy data to help develop against. This can be found in:

Setup > Quote Calculators > Edit > Manage Webhooks > Send Test

Cases

Case Rule Payload

Below is an example payload for a webhook raised in Hoowla via case rules.

{
  "rule_name": "my rule name",
  "rule_run": "2020-01-01 01:02:03",
  "rule_run_by": 1234,
  "case_id": 2345,
  "taskgroup_name": "New Workflow (derived from Remortgage)",
  "task_id": 3456,
  "task_name": "Closed",
  "status_id": null,
  "status_name": null
}

Name	Type	Desc
rule_name	string	the name given to the rule inside Hoowla
rule_run	string	the datetime of when the rule was fired (as it could be a few seconds before you receive the webhook)
rule_run_by	int	the id of the user who triggered the rule to fire
case_id	int	the case the rule fired within
task_id	int	the task/milestone the rule fired within
task_name	string	the name of the task/milestone the rule fired within or for
status_id	int	the status/todo item which this rule fired against
status_name	string	the name of the status/todo item which this rule fired against

You can also customize the rule webhooks with variable placeholders, e.g. @case-id@ and @reference-number@. Entered into the URL, this will be replaced by their custom fields on sending.

Person Added Payload

Below is an example payload for a person added payload.

{
  "case":
    {
      "case_id" : 1234
    },
  "person":
    {
      "person_id": 12345,
      "person_title": "Mr.",
      "person_fname": "Frank",
      "person_lname": "Curtis",
      "person_email": "frank@hoowla.com",
      "person_dob": "2020-01-01",
      "person_ni": "NI123456",
      "person_source": "Webhook Example",
      "person_type": "Individual",
      "person_side" : "Buyer",
      "address_line1": "Buckingham Palace",
      "address_line2": "",
      "address_city": "LONDON",
      "address_county": "",
      "address_postcode": "SW1A 1AA",
      "phone_numbers": [
        "01234 567 890",
        "+44 1234 567 890"
      ]
    }
  ]
}

Name	Type	Desc
case_id	int	The id of the case in Hoowla
person_id	int	the id of the person in Hoowla that has been added to the case
person_title	string	the title of the person added to the case
person_fname	string	the first name of the person added to the case
person_lname	string	the last name of the person added to the case
person_email	string	the email address of the person added to the case
person_dob	string	the date of birth of the person added to the case
person_ni	string	the national insurance number of the person added to the case (If available)
person_source	string	the source of the person added to the case (If available)
person_type	string	the company type of the person added to the case
person_side	string	the side of the person added to the case
address_line1	string	the first line of the address of the person added to the case
address_line2	string	the second line of the address of the person added to the case
address_city	string	the city of the address of the person added to the case
address_county	string	the county of the address of the person added to the case
address_postcode	string	the postcode of the address of the person added to the case
phone_numbers	array	an array of phone numbers of the person added to the case

Person Removed Payload

Below is an example payload for when a person is removed from a case.

{
  "case":
    {
      "case_id" : 1234
    },
  "person":
    {
      "person_id": 12345,
      "person_title": "Mr.",
      "person_fname": "Frank",
      "person_lname": "Curtis",
      "person_email": "frank@hoowla.com",
      "person_dob": "2020-01-01",
      "person_ni": "NI123456",
      "person_source": "Webhook Example",
      "person_type": "Individual",
      "person_side" : "Buyer",
      "address_line1": "Buckingham Palace",
      "address_line2": "",
      "address_city": "LONDON",
      "address_county": "",
      "address_postcode": "SW1A 1AA",
      "phone_numbers": [
        "01234 567 890",
        "+44 1234 567 890"
      ]
    }
  ]
}

Name	Type	Desc
case_id	int	The id of the case in Hoowla
person_id	int	the id of the person in Hoowla that has been removed from the case
person_title	string	the title of the person removed from the case
person_fname	string	the first name of the person removed from the case
person_lname	string	the last name of the person removed from the case
person_email	string	the email address of the person removed from the case
person_dob	string	the date of birth of the person removed from the case
person_ni	string	the national insurance number of the person removed from the case (If available)
person_source	string	the source of the person removed from the case (If available)
person_type	string	the company type of the person removed from the case
person_side	string	the side of the person removed from the case
address_line1	string	the first line of the address of the person removed from the case
address_line2	string	the second line of the address of the person removed from the case
address_city	string	the city of the address of the person removed from the case
address_county	string	the county of the address of the person removed from the case
address_postcode	string	the postcode of the address of the person removed from the case
phone_numbers	array	an array of phone numbers of the person removed from the case

Notes Added Payload

Below is an example payload for a purchase quote raised.

{
  "case":
    {
      "case_id" : 1234
    },
  "note":
    {
      "note_id": 12345,
      "note_case": 1234,
      "note_task": "123456",
      "note_user": 1,
      "note_user_full_name": "frank@hoowla.com",
      "note_creator": 1,
      "note_creator_full_name": "frank@hoowla.com",
      "note_text": "Test Note",
      "note_is_alert": 0,
      "note_permissions": "CUSTOM",
      "custom_permissions": [
        {
          "user": 1,
          "created": "2021-05-01 09:50:00"
        }
      ],
      "note_type": "General",
      "note_status": null
    }
  ]
}

Name	Type	Desc
case_id	int	The id of the case in Hoowla
note_id	int	the id of the note in Hoowla that has been added to the case
note_case	int	the case associated with the note added to the case
note_task	int	the task associated with the note added to the case
note_user	int	the id of the user who the note is assigned as being from
note_user_full_name	string	the name of the user who the note is assigned as being from
note_creator	int	the id of the user who created the note
note_creator_full_name	string	the name of the user who created the note
note_text	string	the text content of the note
note_is_alert	boolean	if the note is set as an alert
note_permissions	string	The permissions of the note, which will be one of the following PUBLIC PRIVATE_COMPANY PRIVATE_BRANCH CUSTOM
custom_permissions	array	if the note has CUSTOM Permissions, an array of user_ids with the date they had permissions User - Int Created - String
note_type	string	the name of the type of note.
note_status	string	the status of the note, if not null it will be either: Pending Resolved

Testing Case Webhooks

For Case Rules:

You can access and test these by adding a rule to a workflow in Hoowla. This is in:

Setup > Workflows > Hover-over a milestone (the green circles) > Click "Create Rule" button

View our Help Guide on creating rules

Once you're in the create rule view, you'll need to add an action like below:

Put your URL into the text box and save.

For Person & Notes: