Webhooks

A webhook tells one of your other systems the moment something happens in InTouch. When the event occurs, InTouch sends an HTTP POST, holding details of the event as JSON, to the URL you configure. You could use one to update an external case management system or start a Zapier automation.

There are three webhooks, each found under Settings > API, which needs the Can edit API keys permission:

• Matter State Change: a matter is created, or its state changes
• Task State Change: a task on a matter is completed, marked as outstanding or marked as not applicable
• Form Completion: a form is completed

Adding a webhook

1. Navigate to Settings > API
2. Under Webhooks, select the webhook you want
3. Select Add Webhook
4. Enter the Webhook URL that should receive the event
5. Optional: add up to five Custom Headers, such as a key your service checks, and a Username and Password for basic authentication
6. Tick the events the webhook should be sent for. These differ for each webhook and are described below
7. Optional: select Send Test to send a test request to the URL. If the test fails, the message says why: the URL is not valid, the address could not be found, InTouch could not connect, the certificate is not trusted, there was no response within 15 seconds, your service replied with a status code outside 200 to 299, or it could not be reached for another reason
8. Select Save

You can add up to 100 of each webhook, for example to send different matter templates to different services. Every request carries the header Content-Type: application/json; charset=utf-8 and a User-Agent starting InTouch/, along with any custom headers you added.

Editing a webhook

1. Navigate to Settings > API
2. Under Webhooks, select the webhook you want
3. Select Actions next to the webhook, then Edit
4. Make your changes and select Save

The Password field is blank when you edit a webhook. Leave it blank to keep the stored username and password. To change either, enter both the username and the password.

To stop sending a username and password without deleting the webhook, select Remove credentials, then Save. InTouch no longer sends basic authentication to that URL, and a Send Test after removing them goes without credentials too. Clearing the two fields yourself does not remove them.

The same Actions menu has Clone, which adds a copy of the webhook without its username and password, and Delete, which removes it. Each asks you to confirm first.

Matter State Change

Sent when a matter is created, or when its state changes. A matter created by a form submission that is held for review counts as created once the submission is accepted. Matters that InTouch archives automatically do not send it. Tick the matter templates it should be sent for; matters created from other templates do not trigger it.

previousState is null when the matter has just been created. Matter states are sent by name: Lead, Open, On Hold, Completed, Closed, Completed & Archived, Aborted and Deleted.

{
  "eventName": "Matter State Change Webhook",
  "matterGuid": "0b9e3c7a-5f1d-4a2e-9c8b-3d6f1e2a7b45",
  "matterItrCode": "[ITR:491D-1ED]",
  "previousState": "Lead",
  "newState": "Open",
  "matterTemplateGuid": "7c2f8a1e-4b3d-4e6f-8a9b-1c2d3e4f5a6b",
  "matterTemplateName": "Residential Sale",
  "triggeredByName": "Sarah Connor",
  "triggeredByEmail": "sarah.connor@example.com",
  "timestamp": "2026-10-18T09:15:42Z"
}

matterItrCode is the matter’s ITR code. In both payloads, triggeredByName and triggeredByEmail are the person who made the change. When the change was made through the API, the name is API Key followed by the key’s name, and the email is null.

The payload does not say why a matter was aborted. When newState is Aborted, use the API’s Read Matter with the matter.abortedreason and matter.abortedcomment data markers to get the reason chosen and the comment given. Both are empty if the matter was aborted without a reason.

Task State Change

Sent when a task on a matter changes state. Choose which changes it is sent for:

• Task Completed
• Task marked as outstanding
• Task marked as not applicable

Then tick the tasks it applies to, grouped by matter template. Only tasks that come from a matter template can trigger it; a task added to a single matter cannot. Task states are sent by name: Outstanding, Completed and Not Applicable.

{
  "eventName": "Task State Change Webhook",
  "taskGuid": "6db90198-bd3c-4656-b9e9-6070652aab52",
  "taskName": "Send client care letter",
  "previousState": "Outstanding",
  "newState": "Completed",
  "matterGuid": "0b9e3c7a-5f1d-4a2e-9c8b-3d6f1e2a7b45",
  "matterItrCode": "[ITR:491D-1ED]",
  "taskTemplateGuid": "11be3e87-9e83-40e9-8389-882919cfc1b0",
  "triggeredByName": "Sarah Connor",
  "triggeredByEmail": "sarah.connor@example.com",
  "timestamp": "2026-10-18T09:15:42Z",
  "taskTemplateName": "Send client care letter"
}

Responding to a webhook

Return any status code from 200 to 299 to show the webhook was received. Field names are in camel case, as in the examples. We add new fields to payloads over time, so ignore any you do not recognise.

If your service returns any other status code, or InTouch cannot reach it at all (the address does not resolve, the connection is refused, the certificate is not trusted or there is no response within 100 seconds), InTouch tries again after 10 minutes, then 1 hour, then 3 hours, then 24 hours. If the fifth attempt also fails, InTouch emails your organisation’s Automation Expert address, if one is set. The email gives the status code your service returned, or says that no response was received.

Dates and times

Dates and times that InTouch sets, such as timestamp, are sent in UTC, in the ISO 8601 format yyyy-MM-ddTHH:mm:ssZ, for example 2026-10-18T09:15:42Z. The matter details a legacy form sends include the exchange and completion dates, keydates.exchange and keydates.completion. When either is set up as a date with no time, it arrives as midnight UTC on the day entered: 2026-06-15T00:00:00Z for 15 June. A form’s own answers are sent as they were submitted, so a date answer arrives as 2026-06-15, and a date and time answer on a form arrives with milliseconds, such as 2026-06-15T08:15:00.000Z.