Mediahawk integration

Overview

Mediahawk is a third-party call tracking platform. The integration receives a webhook from Mediahawk for each tracked inbound call, retrieves the call transcript via the Mediahawk REST API, uses an LLM to categorise the call and extract care details, then creates a contact, an enquiry, and a timeline entry in Found CRM. Attribution data (UTM parameters, Google Click ID, media channel/owner, campaign) is captured against the enquiry.

Data flow: Mediahawk webhook → Found CRM webhook receiver → transcript fetched from Mediahawk REST API → LLM categorisation → contact + enquiry created in Found CRM.

What you'll need before you start

From your Mediahawk account:

• An active Mediahawk account with speech analytics enabled. This is a paid Mediahawk add-on and is mandatory — without it, transcripts cannot be retrieved and every call will be recorded as FAILED.

• An API key, generated from Manage → API Settings in the Mediahawk portal.

• Permission to create webhook steps under Manage → Webhooks.

• The list of tracked phone numbers (destinations) you want surfaced as enquiries in Found CRM.

From your Found Pro workspace:

• A user with the Admin role. Manager and Staff roles cannot configure the integration.

• The MEDIAHAWK_INTEGRATION feature flag enabled on your workspace. If it is not visible, raise a request with Found support to enable it.

• The Found CRM location IDs for each site you want to receive tracked calls. You will copy these from the Found CRM setup screen in step 4.

You will be configuring one Mediahawk webhook per location, pointing at a single Found CRM endpoint.

Step-by-step setup

Step 1 — In Mediahawk: confirm speech analytics is on

Without speech analytics, the integration cannot work. Confirm with your Mediahawk account manager that it is enabled on the account before continuing.

Step 2 — In Mediahawk: generate an API key

Go to Manage → API Settings in the Mediahawk portal and create an API key. Copy and keep it safe — you will use it twice: once to authenticate Found CRM to Mediahawk, and once as the Authorization header value on every webhook.

Step 3 — In Found CRM: add the API key

Sign in as an Admin and go to Settings → Integrations → Mediahawk → Secrets. Paste the API key. The key is stored encrypted and displayed masked (****…****) thereafter.

Step 4 — In Found CRM: open webhook setup for a location

Go to Settings → Integrations → Mediahawk → Webhook setup and select the Found CRM location you are configuring. The screen will display:

• The webhook receiver URL to send Mediahawk traffic to.

• A payload template pre-populated with that location's locationId.

• The Authorization header value to use on the webhook.

Keep this screen open — you will copy from it in the next step.

Step 5 — In Mediahawk: create the webhook step

In the Mediahawk portal go to Manage → Webhooks (https://www.reports.mediahawk.co.uk/manage/webhooks/0) and create a new step using the values from step 4:

{
  "locationId": "<your-found-crm-location-id>",
  "callMhid": "__CallMHID__",
  "callId": "__CallID__",
  "serviceNumber": "__ServiceNumber__",
  "callerNumber": "__CallerNumber__",
  "destinationNumber": "__DestinationNumber__",
  "callStart": "__CallStart__",
  "campaignDescription": "__CampaignDescription__",
  "lastClickSource": "__LastClickSource__",
  "lastClickMedium": "__LastClickMedium__",
  "firstClickSource": "__FirstClickSource__",
  "firstClickMedium": "__FirstClickMedium__",
  "firstClickKeyword": "__FirstClickKeyword__",
  "lastClickKeyword": "__LastClickKeyword__",
  "googleClickId": "__GoogleClickID__",
  "mediaChannel": "__MediaChannel__",
  "mediaOwner": "__MediaOwner__",
  "mediaDescription": "__MediaDescription__",
  "pcSource": "__PCSource__",
  "pcMedium": "__PCMedium__",
  "pcCampaign": "__PCCampaign__",
  "pcContent": "__PCContent__",
  "paidSearchCampaignId": "__PaidSearchCampaignID__",
  "paidSearchCampaignName": "__PaidSearchCampaignName__",
  "pageUrl": "__PageURL__",
  "landingPageUrl": "__LandingPageURL__"
}

Notes:

• __Field__ tokens are Mediahawk placeholders. Mediahawk substitutes them automatically at send time. Leave them as-is.

• callId and locationId are the only strictly required fields. Empty values for other fields are accepted.

• Authentication is by the Authorization header value matching the API key you stored in step 3. A mismatch causes the call to be rejected at the receiver.

Step 6 — In Mediahawk: attach the tracked numbers

Inside the same webhook step, attach the tracked phone numbers (destinations) you want to flow to this Found CRM location. Numbers not attached to the step will not reach Found CRM.

Step 7 — Repeat steps 4–6 for every location

Each Found CRM location is a separate Mediahawk webhook step. All steps point to the same Found CRM URL — what routes the call to the correct location is the locationId in the body.

Step 8 — Place a test call and verify

Call one of the tracked numbers. Then, in Found CRM, go to Settings → Integrations → Mediahawk → Event log. You should see an event progress through:

• PROCESSING — webhook received and authorised. The transcript is being fetched.

• SUCCESS — call processed. Either an enquiry was created, or the call was filtered intentionally (e.g. categorised by AI as CALL_TOO_SHORT).

• FAILED — see "Common failure outcomes" below.

A successful enquiry will appear in the standard enquiries list for that location, with a timeline entry showing it was created via a Mediahawk tracked call and an AI-generated summary.

Step 9 — Reprocess failures (optional)

Failed events can be retried from the event log by an Admin. Reprocessing re-runs the full pipeline (transcript fetch, LLM categorisation, enquiry creation). Only events with status FAILED can be reprocessed.

Common failure outcomes

Things to be aware of

• Processing is not instant. The transcript must exist in Mediahawk before Found CRM can categorise the call. Found CRM polls Mediahawk for up to 2 hours (5 attempts, with exponential backoff from 5 minutes to 2 hours).

• Not every call becomes an enquiry. The AI categoriser excludes calls that are too short or are not enquiries (e.g. professional referrals). These still appear in the event log as SUCCESS but produce no enquiry.

• Phone matching: the caller's number is normalised to E.164 (UK 0… becomes +44…) and used to match an existing contact, otherwise a new one is created. Reprocessing the same call will not duplicate the contact or enquiry.