Lead Connector Logo
All integrations
Custom integration architecture

Build reliable Lead Connector webhook integrations

Use webhooks when an external system needs to start a CRM workflow or receive a CRM event in near real time. A reliable integration needs more than a URL: define the event contract, authentication, unique IDs, retry behavior, monitoring and data ownership.

Discuss your integrationExplore marketing automation

Quick answer

Use an inbound webhook to start a workflow from an external event. Use an outbound webhook action to send workflow data to another service. Protect the endpoint, validate the payload, require a unique event ID, return a clear status and make repeated delivery safe.

What you can build

  • Receive external leads or events into workflows
  • Send CRM events to internal systems or supported apps
  • Transform payloads through a controlled backend
  • Prevent duplicate processing with event IDs
  • Monitor delivery and replay failed events
  • Keep credentials out of browsers and public pages

Before you start

  • A documented source and destination system
  • An HTTPS endpoint controlled by a trusted party
  • An authentication or signature method
  • A JSON schema with required and optional fields
  • A unique event ID and retry policy
  • Logs that exclude secrets and unnecessary personal data

Step-by-step implementation plan

1

Choose inbound or outbound direction

Inbound starts a Lead Connector workflow. Outbound sends a workflow event to another system. Use separate endpoints when responsibilities or security differ.

2

Write the event contract

Document event type, version, IDs, timestamps, required fields, optional fields and example responses before building.

3

Secure the request

Use HTTPS and an authorization header or verifiable signature. Store secrets in server-side environment variables and rotate exposed credentials.

4

Validate and normalize

Reject malformed requests, normalize email and phone where needed and map only approved fields into the CRM or destination.

5

Make processing idempotent

Persist the event ID and return the same outcome for a repeat delivery rather than creating another contact, task, payment or alert.

6

Monitor and recover

Record status, latency and safe error details. Define retries for temporary failures and a manual replay process for permanent failures.

Practical workflow recipes

Inbound lead distribution webhook

Trigger

External platform posts a new lead event

Actions

  • Authenticate request
  • Validate required fields
  • Create or update contact
  • Assign owner
  • Return event status

Result

External leads enter a governed CRM workflow with duplicate protection.

Outbound sales event

Trigger

Qualified opportunity or stage change

Actions

  • Build minimal JSON payload
  • Sign request
  • POST to destination
  • Record response
  • Retry temporary failures

Result

Another system receives a reliable event without direct access to the CRM.

Payment-to-service activation

Trigger

Successful payment

Actions

  • Confirm transaction ID
  • Send service event
  • Create onboarding task
  • Record processed status

Result

Service activation follows verified payment and repeated delivery remains safe.

Recommended data map

event_idIdempotencyA unique immutable value per source event
event_typeRoutinglead.created or payment.received
occurred_atAudit and orderingISO 8601 timestamp
record_idEntity referenceContact, opportunity or transaction ID
sourceOwnership and diagnosticsfacebook, booking-page or billing-service
dataApproved business payloadOnly fields required by the receiving workflow

Reliability and security controls

  • Use one stable contact identifier, normally email or phone, to update an existing record instead of creating duplicates.
  • Map only the fields the workflow needs and document the system that owns each field.
  • Add filters, stop conditions and re-entry rules before publishing so the same event does not create repeated actions.
  • Test with a record you can identify, then verify the contact, opportunity, task, message and execution log.
  • Limit access tokens, webhook secrets and connected accounts to the smallest required scope. Never place secrets in a public page or payload.

Troubleshooting

Unauthorized response

Compare the configured header name and value, check secret scope and deployment context, then rotate the secret if it was exposed.

Required ID is missing

Map a real immutable source event, transaction or subscription ID. Do not use a constant test value in production.

The sender retries successful events

Return a documented 2xx response promptly after accepted processing and use asynchronous work for slow downstream actions.

Events arrive out of order

Compare occurrence timestamps or source sequence numbers and make state changes conditional on newer data.

Availability note

Connectors, events, actions and usage charges can vary by plan, account and region. Verify the options shown in your account and test them before publishing.

Frequently asked questions

What is the difference between inbound and outbound webhooks?

An inbound webhook receives an external event and can start a workflow. An outbound webhook sends workflow data from Lead Connector to another endpoint.

How do I prevent webhook duplicates?

Require a unique event ID, store the processed result and make repeated delivery return the prior outcome without repeating side effects.

Where should webhook secrets be stored?

Store secrets only in server-side environment variables or a secret manager. Do not place them in page code, query strings, public repositories or visible payloads.

Should a webhook return success before all work finishes?

For slow processes, acknowledge accepted events quickly and complete the work asynchronously, while preserving logs and retry handling.

Related integration guides

Shopify

Read guide

LinkedIn Lead Ads

Read guide

TikTok Lead Ads

Read guide

Turn the connection into a measurable process

Connect the event to an owner, next action and outcome, then test it before launch.

Discuss your integration