Receive lead events

Have LeadTruffle send events to your application when a lead arrives, a conversation finishes, or another supported event occurs.

Prepare your receiver

Create an HTTPS endpoint in your application that accepts JSON POST requests. Keep the raw request body available so you can verify signed requests before parsing JSON.

Use V2 webhooks for new integrations. You will need your LeadTruffle API key, your receiver's URL, and a shared secret for signature verification.

Choose an event

Event	Use it to
`LEAD_CREATED`	Capture a lead as soon as it arrives
`CONVERSATION_COMPLETED`	Receive the completed conversation and collected details
`MESSAGE_REPLY`	React to a message reply
`CLIENT_STATUS_CHANGED`	Track changes to a contact's pipeline status
`NEW_APPOINTMENT`	Receive a new calendar booking
`YELP_MESSAGE_OUTBOUND`	Connect outbound Yelp messages to your integration

The Create V2 webhook reference includes payload examples and the full set of supported event values.

Register your webhook

This request creates a webhook subscription. Replace the example URL with your receiver and use your own shared secret.

curl --request POST \
  --url 'https://pub-api.leadtruffle.com/api/v2/pub/webhooks' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "eventType": "LEAD_CREATED",
    "url": "https://your-app.example/webhooks/leadtruffle",
    "secret": "YOUR_WEBHOOK_SECRET"
  }'

A successful registration returns HTTP 201. Keep the webhook ID from the response so you can update or remove the subscription later.

Verify incoming deliveries

Follow Verify webhook signatures to check the timestamp and signature against the raw request body. The shared secret is separate from your LeadTruffle API key.

Design your receiver so a duplicate event cannot create duplicate downstream actions. Save the incoming event before handing off slow work.

Confirm the integration

Use List V2 webhooks to verify the registration. Then confirm that a matching event reaches your receiver and that your application processes it successfully. Registration alone does not verify delivery.

Use Update V2 webhook to change a destination or disable a subscription.