Triggers & Webhooks
Relevant source files
The following files were used as context for generating this wiki page:
The Triggers and Webhooks system serves as the entry and integration gateway for the GoHighLevel Clone automation platform. Triggers act as the "Event" in the Event-Action-Result-State (EARS) framework, initiating Workflow Executions when specific conditions are met within the CRM, funnels, or external systems. Webhooks provide a bidirectional integration layer, allowing the platform to both receive external data to trigger workflows and push data to third-party services as an automated action step.
This module is designed with Domain-Driven Design (DDD) principles, ensuring that every trigger event is validated, logged, and scoped to specific accounts to maintain multi-tenant isolation. The system supports 26 distinct trigger types across 7 categories, ranging from contact updates to payment received events.
Trigger Architecture & Types
The trigger system is categorized into several domains, each monitoring specific lifecycle events of a contact or a transaction. When a trigger event occurs, the system initializes a workflow in a "draft" or "active" state, preparing a blank canvas or executing a predefined sequence of steps.
Trigger Categories
| Category | Description | Common Types |
|---|---|---|
| Contact | Events related to CRM contact records | contact.created, contact.tagAdded, contact.birthday |
| Form/Survey | User interactions with capture elements | form.submitted, survey.completed |
| Pipeline | Sales stage transitions and deal status | pipeline.stageChanged, deal.won |
| Appointment | Calendar and booking interactions | appointment.booked, appointment.cancelled |
| Payment | Financial transactions and subscriptions | payment.received, subscription.created |
| Communication | Engagement with outbound messages | email.opened, sms.replied, call.completed |
| Time | Schedule-based or date-based initiators | specific.datetime, recurring.schedule |
Sources: specs/workflows/plan.md, frontend/VISUAL_BUILDER_QUICK_REFERENCE.md
Trigger Workflow Logic
The following diagram illustrates how a trigger event initiates the workflow execution engine.
The system ensures that triggers only initiate workflows if the contact has not opted out (GDPR/CAN-SPAM compliance) and if the account hasn't exceeded concurrent execution limits.
Sources: DDD_IMPLEMENTATION_REPORT_SPEC_WFL_005.md
Webhook System
Webhooks in this platform function in two primary modes: Inbound (Triggers) and Outbound (Actions). This allows for seamless integration with external tools like Zapier, Make, or custom third-party APIs.
Inbound Webhooks (Trigger)
Workflows can be initiated via a webhook.received event. The system generates a unique endpoint for the workflow that accepts HTTP requests (GET, POST, etc.). Upon receiving a valid payload, the system extracts contact identifiers and initializes the automation sequence.
Sources: frontend/VISUAL_BUILDER_QUICK_REFERENCE.md, specs/workflows/plan.md
Outbound Webhooks (Action)
As part of an automation sequence, the webhook.call action sends data to an external URL.
Key Configuration for Webhook Actions:
- Methods: GET, POST, PUT, PATCH, DELETE.
- Authentication: Supports None, Basic Auth, Bearer Token, and API Key.
- Payload: Sends data in JSON format.
- Retry Logic: Implements exponential backoff (60s, 120s, 240s) for failed deliveries.
- Security: Signature-based verification using HMAC is used to ensure delivery integrity.
Sources: specs/workflows/plan.md, FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md, frontend/VISUAL_BUILDER_QUICK_REFERENCE.md
Webhook Execution Flow
The platform uses an enhanced executor for webhooks that categorizes errors to determine if a retry is warranted.
Configuration & Persistence
Triggers and webhooks are persisted in the database with strict constraints to ensure system stability. Webhook deliveries are tracked in a webhook_deliveries table to provide a full audit trail of integrated communications.
Data Model: Integrations & Webhooks
| Field | Type | Description |
|---|---|---|
id | UUID | Unique identifier for the integration/webhook |
url | String | Target destination for outbound calls |
event_type | Enum | The specific event triggering the webhook |
status | String | Current state (active, inactive, failing) |
retry_count | Integer | Number of attempts made for a specific delivery |
signature_key | Encrypted | Key used for HMAC header generation |
Sources: FUNNELS_BACKEND_IMPLEMENTATION_REPORT.md, IMPLEMENTATION_REPORT_SPEC_WFL_003.md
Configuration Validation
Trigger and webhook configurations are validated using Pydantic schemas in the backend and Zod schemas in the frontend. For example, a webhook action requires a valid HTTP/HTTPS URL and will fail validation if the URL format is incorrect or if required authentication headers are missing.
Sources: IMPLEMENTATION_REPORT_SPEC_WFL_003.md, frontend/VISUAL_BUILDER_QUICK_REFERENCE.md
The Triggers & Webhooks module is a critical component for both internal automation and external extensibility. By supporting a vast array of event types and providing a resilient webhook delivery system with exponential backoff and HMAC security, the platform ensures that business-critical data flows reliably between the CRM and the broader software ecosystem.