Jonathon's AI Wiki

Webhooks

6 min read

Source: ai-research/ghl-2026-05-01/docs-category-webhook.md, ai-research/ghl-2026-05-01/support-solutions-articles-155000007078-developer-guide-to-highlevel-s-webhook-logs-dashboard.md, ai-research/ghl-2026-07-02-drain/marketplace-docs-webhook-integration-guide.md

HighLevel publishes 50+ real-time webhook events covering contacts, conversations, appointments, opportunities, invoices, products, tasks, users, and Marketplace app lifecycle. Webhooks are subscribed via Marketplace app configuration and delivered to the URL the app registers. The Webhook Logs Dashboard at Developer Portal → Insights → Logs gives every developer instant visibility into payloads, response codes, and retry history with 30-day retention.

Key Takeaways

  • 50+ events are published in real time. Categories cover contacts, conversations, appointments, opportunities, invoices, products, prices, orders, tasks, users, locations, notes, campaigns, associations, records/relations, app lifecycle, and Voice AI calls.
  • Subscription via Marketplace app config. Webhooks are configured on the Marketplace app, not per-tenant. Each install of the app inherits the event subscriptions defined on the listing.
  • Webhook Logs Dashboard at Developer Portal → Insights → Logs records every outbound webhook with full payload, headers, response code, and retry history. 30-day retention.
  • Substring search across payloads. The dashboard’s global search supports partial matches, so any value (email, contact ID, event name) can be located instantly.
  • Filter by ID, event type, time range, status code. Detail panel shows webhook ID, attempt number, event name, timestamp history (created/delivered/retried), HTTP response code, and full JSON payload with one-click copy.
  • Timezone-aware. Default Central Time, but every developer can pick their own — the selection is saved per user and does not affect teammates.
  • Failures and retries are visible. Each attempt (including failures and retries) appears with its response code and timestamp. Logs are read-only — viewing them does not consume API rate limits.
  • No direct export. Payloads can be copied individually, or webhook data can be retrieved via API. After 30 days logs are permanently deleted, so save anything needed for compliance.
  • Signed payloads. Every webhook body is signed. Two headers exist today — legacy X-WH-Signature (RSA-SHA256) and current X-GHL-Signature (Ed25519) — and the legacy header is deprecated July 1, 2026. See Verifying Webhook Authenticity below.

Event Catalog (from official docs)

The Webhook docs landing page lists these event types:

App lifecycle: AppInstall, AppUninstall, AppUpdate, PlanChange.

External auth: ExternalAuthConnected (called when external authentication — OAuth2 or Basic — is connected for an app/location/company).

Contacts: ContactCreate, ContactUpdate, ContactDelete, ContactDndUpdate, ContactTagUpdate.

Conversations & messaging: InboundMessage, OutboundMessage, ProviderOutboundMessage (when a custom provider is the default channel), ConversationUnreadWebhook, LCEmailStats.

Appointments: AppointmentCreate, AppointmentUpdate, AppointmentDelete.

Opportunities: OpportunityCreate, OpportunityUpdate, OpportunityDelete, OpportunityStatusUpdate, OpportunityStageUpdate, OpportunityAssignedToUpdate, OpportunityMonetaryValueUpdate.

Invoices: InvoiceCreate, InvoiceUpdate, InvoiceDelete, InvoicePaid, InvoicePartiallyPaid, InvoiceSent, InvoiceVoid.

Orders: OrderCreate, OrderStatusUpdate.

Products & pricing: ProductCreate, ProductUpdate, ProductDelete, PriceCreate, PriceUpdate, PriceDelete.

Tasks: TaskCreate, TaskComplete, TaskDelete.

Users: UserCreate, UserUpdate, UserDelete.

Locations: LocationCreate, LocationUpdate.

Notes: NoteCreate, NoteUpdate, NoteDelete.

Campaigns: CampaignStatusUpdate.

Associations & objects: AssociationCreate, AssociationUpdate, AssociationDelete, ObjectSchemaCreate, ObjectSchemaUpdate, RecordCreate, RecordUpdate, RecordDelete, RelationCreate, RelationDelete.

SaaS & Voice: SaaSPlanCreate, VoiceAiCallEnd.

The official source is the Webhook docs landing page, which is the authoritative list — confirm the current set there before depending on a specific event name.

Verifying Webhook Authenticity

Webhooks can be spoofed by malicious actors, so HighLevel signs every webhook body and publishes public keys to verify it. Two signature headers exist during the current transition period:

HeaderAlgorithmStatus
X-WH-SignatureRSA-SHA256Legacy — deprecated July 1, 2026. Use only for backward compatibility until then.
X-GHL-SignatureEd25519Current. Use this when present; HighLevel will rely only on this header going forward.

Recommended verification flow:

  1. If X-GHL-Signature is present, verify it using the published Ed25519 public key.
  2. If only X-WH-Signature is present (transition period), verify it using the published legacy RSA public key.
  3. Reject the request if verification fails.

Every payload also carries a Timestamp (UTC) and a Webhook ID, so requests can be uniquely identified and time-validated to prevent replay attacks — check both before trusting a payload, not just the signature.

Node.js example for the legacy RSA signature (adapt for X-GHL-Signature/Ed25519 using the current public key published on the live docs page):

const crypto = require('crypto');
const legacyPublicKey = `<paste_legacy_public_key_from_docs>`;
 
function verifyLegacy(payload, signature, publicKeyPem) {
  if (!signature || signature === 'N/A') return { ok: false, reason: 'no signature' };
  try {
    const verifier = crypto.createVerify('SHA256');
    verifier.update(payload);
    const ok = verifier.verify(publicKeyPem, signature, 'base64');
    return { ok, reason: ok ? null : 'verify failed' };
  } catch (e) {
    return { ok: false, reason: e.message };
  }
}

Action item: any integration still checking only X-WH-Signature needs to switch to X-GHL-Signature (Ed25519) before July 1, 2026, or verification will silently stop working once HighLevel drops the legacy header.

Using the Webhook Logs Dashboard

Setup:

  1. Sign in at marketplace.gohighlevel.com and navigate to Developer Portal → Insights → Logs.
  2. Select the Webhook Logs tab.
  3. (Optional) Adjust the timezone in the top-right corner.
  4. Trigger an event in your app to generate a test webhook.
  5. Enter a unique identifier (such as an email) into the search bar to locate the event.
  6. Click the row to open the detail panel — review payload and response.
  7. Use the Copy button to grab the payload for replay in Postman or webhook.site.

Key benefits called out in the official guide:

  • Instant delivery verification — confirm immediately whether HighLevel delivered or retried a webhook.
  • Full payload visibility — JSON payloads and headers, exactly as delivered (no masking, no truncation).
  • 30-day log retention.
  • Reduced dependency on Support — debug delivery issues without filing a ticket.
  • Sub-account-aware — the dashboard displays webhook events associated with the developer account and its applications.

Access control: Only users with Developer Portal permissions can view the Webhook Logs Dashboard.

Open Questions

  • Automated retry behavior. The Webhook Logs Dashboard shows attempt numbers and retry history (so retries definitely happen), but the exact retry count, back-off schedule, and max age are not specified in the sources reviewed for this article — confirm against the Automated Webhook Retries support article before relying on specific timing.

Try It

  1. In your Marketplace app config, subscribe to the minimal set of events your integration needs (e.g., ContactCreate, ContactUpdate, InboundMessage).
  2. Stand up a webhook receiver — even a webhook.site URL is fine for the first test.
  3. Trigger the event in a test sub-account and verify it appears in Developer Portal → Insights → Logs within seconds.
  4. Inspect the payload structure for each event type before writing handler code — payloads are unmasked, so design idempotency around the IDs you see.
  5. Build idempotency keys from the event ID + entity ID. HighLevel retries on failure, and your handler must tolerate duplicate deliveries.
  6. Set up an alert that fires when a webhook handler returns a non-2xx response — the dashboard will show those, but you do not want to discover them by reading logs.
  7. Implement signature verification against X-GHL-Signature (Ed25519) now rather than waiting — the legacy X-WH-Signature (RSA-SHA256) path stops working July 1, 2026.

Graph View

Backlinks