Inbound Webhooks

Create Webhook

POST /backend/webhooks

Body Parameters

string

required

URL that will receive notifications

array

required

List of events to subscribe to

boolean

default:"true"

Whether webhook is active

Request Example

curl -X POST "https://api.leavo.ai/backend/webhooks" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/leavo",
    "events": ["lead.created", "lead.status_changed", "message.received"],
    "active": true
  }'

const response = await fetch('https://api.leavo.ai/backend/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://your-app.com/webhooks/leavo',
    events: ['lead.created', 'lead.status_changed', 'message.received'],
    active: true
  })
});

Response

{
  "success": true,
  "data": {
    "id": "webhook-uuid",
    "url": "https://your-app.com/webhooks/leavo",
    "events": ["lead.created", "lead.status_changed", "message.received"],
    "active": true,
    "secret": "whsec_xxxxxxxxxxxxx",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Store the secret securely. It’s used to verify that requests actually came from Leavo.

Create a Pipeline Deal

Besides creating or updating the lead, an inbound webhook can drop it straight onto the CRM board, so leads from a form or an ad land in the pipeline automatically.

string

Pipeline where a deal should be created for the received lead

string

Stage the deal should land in

{
  "target_pipeline_id": "bb0e8400-e29b-41d4-a716-446655440000",
  "target_stage_id": "cc0e8400-e29b-41d4-a716-446655440000"
}

The two fields are a pair: send both or neither. Sending only one returns 400.

To disable deal creation on an existing webhook, send target_pipeline_id as the zero UUID (00000000-0000-0000-0000-000000000000) — this clears both fields.

Behavior

The deal is created after the lead

The lead is created or updated first. Only then is the deal created and linked to it.

Failures never break lead ingestion

If deal creation fails — deleted stage, removed pipeline, invalid configuration — the error is logged and the request still returns success. Taking in the lead is the webhook’s core job; the deal is a bonus.

The target stage cannot be the lost stage

A webhook never silently creates already-lost deals. A lost target stage is refused.

History records a system actor

Since there is no authenticated user on a webhook call, the deal_created event shows up in the deal history with actor_type: "system".

Signature Verification

Every webhook includes an X-Leavo-Signature header. Verify it to ensure authenticity:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Overview

Leads

Status

Tags

Knowledge Base

Pipeline (CRM)

Webhooks

Custom Fields

Cadences

Conversations

Messages

Departments

File Uploads

Templates (Meta/Gupshup)

Follow-up

Create Webhook

Body Parameters

Request Example

Response

Create a Pipeline Deal

Behavior

Signature Verification

​Create Webhook

​Body Parameters

​Request Example

​Response

​Create a Pipeline Deal

​Behavior

​Signature Verification

Create Webhook

Body Parameters

Request Example

Response

Create a Pipeline Deal

Behavior

Signature Verification