Skip to content
Karpa Partner Docs

CRM Webhook

Karpa sends a signed message to your endpoint whenever something important happens for your customers: a lead opts in, a Case is submitted or resolved, a payment succeeds, or a prescription is sent or shipped. This guide covers the connection, how to verify the signature, and how to check a message really came from Karpa.

Overview

If you use a marketing CRM (like HubSpot or GoHighLevel) to run email/SMS campaigns, you can have Karpa notify your CRM automatically whenever something important happens for your customers, for example when someone submits an intake form. Karpa does this by sending a small, structured message to a web address (“endpoint”) that you provide. Your CRM (or a small relay service in front of it) receives that message and updates your CRM however you’ve set it up.

You don’t need to build anything Karpa-specific inside your CRM. You need one URL that can receive a POST request over HTTPS, and a private “signing secret” so your endpoint can verify each message really came from Karpa.

This is a marketing/retention integration, not a clinical one. It carries only the customer contact and business information a marketing tool needs (see “What’s excluded” in the technical reference).

Setup (Settings → Integrations)

  1. Endpoint URL: the public HTTPS address that will receive Karpa’s messages. Karpa rejects addresses that aren’t reachable from the public internet, including localhost and internal network addresses.
  2. Signing secret: a secret string you choose (or your CRM/relay generates). Karpa encrypts and stores this; it is never shown back to you after saving, and never appears in Karpa’s logs.
  3. BAA-covered confirmation: a checkbox confirming the CRM or relay you’re sending data to is covered by Karpa’s existing Business Associate Agreement (BAA) with your organization. (This reuses your organization’s existing signed BAA; there’s no new paperwork to sign here.)
  4. Send a test delivery: before you can turn the destination on, Karpa sends a harmless “ping” message (no real customer data) to your endpoint, signed exactly like a real message would be. Your endpoint needs to receive it and respond successfully before you can activate.
  5. Activate: once the test succeeds and the BAA box is checked, you can turn the destination on.

Important: if you ever change the endpoint URL or the signing secret, Karpa automatically turns the destination off again until you send a new successful test. This protects against accidentally sending real customer data to an endpoint that hasn’t been verified yet.

What each lead now includes

Alongside the lead’s contact details, Karpa sends two optional blocks on every message:

  • Attribution: the campaign parameters on the link that brought the customer in (UTM source/medium/campaign/content/term, the ad-platform click IDs), plus the landing page path and the referring site. The first non-campaign-crediting arrival is kept as the acquisition source, so a later branded search does not take credit from the ad that created the demand; the most recent arrival is also included on the lead message as latest.
  • Consent: when the customer accepted the intake disclosure and which version of the wording they saw, so a consent record can be produced later rather than merely asserted.
  • Contact consent (only if you turn it on): whether the customer agreed to be called on the two lead messages, including calls that use an artificial, prerecorded, or AI-generated voice. Karpa writes the wording; you choose whether it is asked in Settings → Patient Experience, and turning it on also requires the customer to give a phone number at intake.

A customer who declines is sent as a clear “no”, so you can tell a refusal from a customer who was never asked. Karpa sends the answer once, when the lead is created: if a customer later revokes, no message corrects the earlier one, and honoring that revocation is yours as the party doing the calling.

Tag your links, or attribution is empty. Attribution is captured from the landing request, so it only exists if the link carries it. Tag every campaign link with utm_source, utm_medium, and utm_campaign (utm_content and utm_term separate creatives and keywords). Click IDs need no work because ad platforms add them automatically when auto-tagging is on. Untagged traffic arrives as direct and cannot be recovered later.

Two things to set expectations: attributing a journey that spans two devices is not possible from browser data, and if a customer’s browser storage is cleared they count as a new visitor. Both are properties of browser-based attribution, not of this integration.

For engineers

Hand them the technical reference covering the envelope format, signature verification, and deduplication.