Marketing CRM Webhook: Setup Guide

Status: MVP (issue #852). The four events (Lead created, Case submitted, Case resolved, Payment succeeded) are tracked separately in issue #853. This guide covers the parts that are already true today: how the connection works, how to prove your endpoint is really yours, and how to check that a message really came from Karpa.

What this is, in plain terms

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 just need one URL that can receive a POST request over HTTPS, and a private “signing secret” (a password only you and Karpa know) so your endpoint can prove any given message really came from Karpa and not an imposter.

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).

Setting up your destination (Settings → Integrations)

Endpoint URL: the public HTTPS address that will receive Karpa’s messages. It must be a real, publicly reachable internet address, not localhost, an internal company network address, or anything only reachable from inside your own office. Karpa checks this automatically and will reject an address that isn’t safely public.
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.
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.)
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.
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.

For your engineer

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