Webhooks

Webhooks deliver real-time HTTP POST notifications to your endpoint when data changes in a Lofty account. Instead of polling the API, register an HTTPS callback URL and Lofty pushes a JSON payload on each subscribed event.

POST https://api.lofty.com/v1.0/webhook

{
  "listId": 2,
  "callbackUrl": "https://your-app.example.com/webhooks/lofty",
  "limit": 100
}

Field	Type	Required	Description
`listId`	integer	Yes	Event type (1–12, see table below)
`callbackUrl`	string	Yes	HTTPS endpoint to receive payloads
`limit`	integer	No	Max events per batch (default 100, max 5000)

The callbackUrl must use HTTPS. HTTP endpoints are rejected.

Manage subscriptions

Method	Endpoint	Description
`POST`	`/v1.0/webhook`	Create a subscription
`GET`	`/v1.0/webhooks`	List active subscriptions
`DELETE`	`/v1.0/webhook/{subscribeId}`	Delete a subscription

Delivery timing

Events to a healthy endpoint are typically delivered within 1 minute of the triggering change. Actual delivery speed depends on your endpoint. Lofty delivers to each endpoint over a limited number of concurrent connections, so a slow handler queues its own events: an endpoint that responds in under a second keeps up with any volume, while one that takes several seconds per request can fall minutes behind at peak — see the throughput note under Best practices. Failed deliveries follow the retry schedule below. Deliveries to a disabled subscription pause and resume automatically after recovery — see Health probes.

Retries and failure handling

A delivery counts as successful when your endpoint returns any 2xx status code. Any other response — an error status, a timeout, or a connection failure — is handled by the rules in this section.

Retry schedule

Failed deliveries are retried up to 9 total attempts within 48 hours, with exponential backoff between attempts:

Attempt	Delay after previous failure
2	30 seconds
3	2 minutes
4	10 minutes
5	30 minutes
6	2 hours
7	6 hours
8	12 hours
9	24 hours

Each delay includes ±20% random jitter so retries from many events don’t arrive in synchronized bursts. An event that still cannot be delivered 48 hours after it was created is discarded.

Response handling

Your response	What Lofty does
`2xx`	Delivered — no further attempts
`408`, `429`, `5xx`, timeout, connection error	Retried on the schedule above
`429` with a `Retry-After` header	Retried after the delay you request (minimum 60 seconds, capped at 1 hour)
`410 Gone`	The subscription is disabled immediately — return 410 when you decommission an endpoint
Any other `4xx`	Not retried — the event is discarded

Idempotent delivery

Every delivery request carries a Lofty-Webhook-Id header. Its value is unique per event and stable across retries. If a timeout caused your response to be lost, the retry arrives with the same Lofty-Webhook-Id — use it to deduplicate instead of processing the event twice.

Endpoint health and automatic disabling

Lofty tracks delivery health per subscription and disables a subscription automatically when:

your endpoint returns 410 Gone — immediately, or
deliveries fail continuously with no successes in between — within hours for high-volume endpoints, or after roughly a day of sustained failures otherwise.

While a subscription is disabled, Lofty stops attempting deliveries to it. Pending events wait for recovery but still expire 48 hours after creation.

Health probes and automatic recovery

Disabled subscriptions receive a ping probe approximately every 6 hours:

{ "eventType": "ping", "webhookId": 123456 }

The first probe that gets a 2xx response re-enables the subscription, and all pending unexpired events are delivered immediately. No manual action is needed on either side.

Your receiver must return 2xx to ping probes. If your endpoint rejects unrecognized event types with an error status, a disabled subscription can never recover automatically. Acknowledge first, then ignore event types you don’t handle.

Notification recipients

Which subscribed users receive a callback depends on the subscription’s delivery mode (permissionMode). In both modes, only users in the lead’s team who have subscribed to the event type are considered.

Assignment-based delivery — `permissionMode: 0` (default)

A subscriber receives the callback only for leads assigned to them or that they administer:

Hidden leads — only the assigned agent receives the notification.
Other leads — the subscriber receives it if they are the assigned agent, or a Company Owner / Company Admin. All other subscribers are excluded.

Ownership-based delivery — `permissionMode: 1`

A subscriber receives the callback for any lead they manage, regardless of who it is assigned to:

Every assignment-based case above still applies (assigned agent, Company Owner / Company Admin).
In addition, the subscriber receives the callback for any lead within their ownership scope — owned by their team or office, or personally owned by them — even if it is assigned to someone else.
Hidden leads are still delivered only to users who manage them.

Ownership-based mode is intended for team/account-level integrations that need to cover every lead in their scope, not only assigned leads. Set permissionMode when creating the subscription; it defaults to 0, so existing subscriptions are unaffected.

Common fields

All payloads include:

Field	Type	Description
`teamId`	integer	Team ID where the event occurred
`listId`	integer	Event type ID (1–12)

Event types

listId	Event	Triggers
1	Agent Info	Agent created or updated
2	Lead Info	Lead created, updated, or deleted
3	Lead Activity	Lead site activity (browse, favorite, search)
4	Listing Alert	Listing alert changed
5	Transaction	Transaction created, updated, or deleted
6	Call	Call event (MANUAL and LOGGED only, excludes AUTO)
7	Email	Email event (MANUAL and LOGGED only, excludes AUTO)
8	Text	Text message event (MANUAL and LOGGED only, excludes AUTO)
9	Note	Note created, updated, or deleted
10	Task	Task created, updated, finished, or deleted
11	Appointment	Appointment created, updated, finished, or deleted
12	Pipeline Change	Lead pipeline stage changed

Call, Email, and Text webhooks do not fire for AUTO communications. Only agent-initiated (MANUAL) and after-the-fact logged (LOGGED) events trigger webhooks. Automated messages sent by Lofty (drip campaigns, auto-responders, Smart Plans, etc.) are excluded. If your integration depends on tracking all communications, you must also poll the Communication API for AUTO type events.

Event payloads

1. Agent Info

Triggered when an agent is created or updated.

{
  "teamId": 123456,
  "listId": 1,
  "updatedAgent": [
    {
      "agentUserId": 789,
      "updateTime": 1736935800000
    }
  ]
}

Field	Type	Description
`updatedAgent`	array	List of updated agent records
`updatedAgent[].agentUserId`	integer	User ID of the updated agent
`updatedAgent[].updateTime`	integer	Epoch milliseconds of the update

2. Lead Info

Triggered when a lead is created, updated, or deleted. Only the relevant action fields are present.

{
  "teamId": 123456,
  "listId": 2,
  "createdLead": [
    { "leadId": 456, "updateTime": 1736935800000 }
  ],
  "updatedLead": [
    { "leadId": 457, "updateTime": 1736935860000 }
  ],
  "deletedLead": [
    { "leadId": 458, "updateTime": 1736935920000 }
  ]
}

Field	Type	Description
`createdLead`	array	Created leads (present on create)
`updatedLead`	array	Updated leads (present on update)
`deletedLead`	array	Deleted leads (present on delete)
`[].leadId`	integer	Lead ID
`[].updateTime`	integer	Epoch milliseconds of the change

3. Lead Activity

Triggered when a lead performs site activity (SiteBrowse, SiteFavorite, SiteSearch, etc.).

{
  "teamId": 123456,
  "listId": 3,
  "updatedLead": [
    { "leadId": 456, "updateTime": 1736935800000 }
  ]
}

Field	Type	Description
`updatedLead`	array	Leads with new activity
`updatedLead[].leadId`	integer	Lead ID
`updatedLead[].updateTime`	integer	Epoch milliseconds of the activity

4. Listing Alert

Triggered when a listing alert changes.

{
  "teamId": 123456,
  "listId": 4,
  "alertId": 789
}

Field	Type	Description
`alertId`	integer	ID of the changed alert

5. Transaction

Triggered when a transaction is created, updated, or deleted. Only the relevant action fields are present.

{
  "teamId": 123456,
  "listId": 5,
  "createdTransaction": [
    {
      "leadId": 456,
      "transactionId": 789,
      "updateTime": 1736935800000
    }
  ],
  "updatedTransaction": [
    {
      "leadId": 457,
      "transactionId": 790,
      "updateTime": 1736935860000,
      "updatedField": { "fieldName": "newValue" },
      "updatedFields": [{ "fieldName": "newValue" }]
    }
  ],
  "deletedTransaction": [
    {
      "leadId": 458,
      "transactionId": 791,
      "updateTime": 1736935920000
    }
  ]
}

Field	Type	Description
`createdTransaction`	array	Created transactions (present on create)
`updatedTransaction`	array	Updated transactions (present on update)
`deletedTransaction`	array	Deleted transactions (present on delete)
`[].leadId`	integer	Associated lead ID
`[].transactionId`	integer	Transaction ID
`[].updateTime`	integer	Epoch milliseconds of the change
`[].updatedField`	object	Changed field key-value pair (nullable)
`[].updatedFields`	array	List of changed field key-value pairs (nullable)

6. Call

Triggered on a call event.

{
  "teamId": 123456,
  "listId": 6,
  "createdCall": [
    {
      "callId": 101,
      "timelineId": 9876,
      "leadId": 456,
      "updateTime": 1736935800000,
      "agentId": 789,
      "communicationType": "MANUAL"
    }
  ]
}

Field	Type	Description
`createdCall`	array	Call event records
`[].callId`	integer	Dialer call record ID (`MANUAL`) or timeline ID (`LOGGED`). Kept for backward compatibility — prefer `timelineId` for new integrations.
`[].timelineId`	integer	Lead timeline row ID for this call event. Always `lead_timeline.id` regardless of `communicationType`. Pass as `communicationId` to `GET /v2.0/communication/call/{communicationId}` to fetch the full record.
`[].leadId`	integer	Associated lead ID
`[].updateTime`	integer	Epoch milliseconds of the call
`[].agentId`	integer	Agent user ID
`[].communicationType`	string	`MANUAL` or `LOGGED`

7. Email

Triggered on an email event.

{
  "teamId": 123456,
  "listId": 7,
  "createdEmail": [
    {
      "emailId": 101,
      "timelineId": 9876,
      "leadId": 456,
      "updateTime": 1736935800000,
      "agentId": 789,
      "communicationType": "MANUAL"
    }
  ]
}

Field	Type	Description
`createdEmail`	array	Email event records
`[].emailId`	integer	Email record ID (`MANUAL`) or timeline ID (`LOGGED`). Kept for backward compatibility — prefer `timelineId` for new integrations.
`[].timelineId`	integer	Lead timeline row ID for this email event. Always `lead_timeline.id` regardless of `communicationType`. Pass as `communicationId` to `GET /v2.0/communication/email/{communicationId}` to fetch the full record.
`[].leadId`	integer	Associated lead ID
`[].updateTime`	integer	Epoch milliseconds of the event
`[].agentId`	integer	Agent user ID
`[].communicationType`	string	`MANUAL` or `LOGGED`

8. Text

Triggered on a text/SMS event.

{
  "teamId": 123456,
  "listId": 8,
  "createdText": [
    {
      "textId": 101,
      "timelineId": 9876,
      "leadId": 456,
      "updateTime": 1736935800000,
      "agentId": 789,
      "communicationType": "MANUAL"
    }
  ]
}

Field	Type	Description
`createdText`	array	Text message event records
`[].textId`	integer	SMS record ID (`MANUAL`) or timeline ID (`LOGGED`). Kept for backward compatibility — prefer `timelineId` for new integrations.
`[].timelineId`	integer	Lead timeline row ID for this text event. Always `lead_timeline.id` regardless of `communicationType`. Pass as `communicationId` to `GET /v2.0/communication/text/{communicationId}` to fetch the full record.
`[].leadId`	integer	Associated lead ID
`[].updateTime`	integer	Epoch milliseconds of the event
`[].agentId`	integer	Agent user ID
`[].communicationType`	string	`MANUAL` or `LOGGED`

communicationType values — MANUAL: agent-initiated communication. LOGGED: communication recorded after the fact. AUTO events are excluded from webhooks.

9. Note

Triggered when a note is created, updated, or deleted. Only the relevant action fields are present.

{
  "teamId": 123456,
  "listId": 9,
  "createdNote": [
    {
      "noteId": 101,
      "leadId": 456,
      "updateTime": 1736935800000,
      "noteType": "Manual",
      "agentId": 789
    }
  ],
  "updatedNote": {
    "noteId": 102,
    "leadId": 457,
    "updateTime": 1736935860000,
    "noteType": "Manual",
    "agentId": 789
  },
  "deletedNote": {
    "noteId": 103,
    "leadId": 458,
    "updateTime": 1736935920000,
    "noteType": "Manual",
    "agentId": 789
  }
}

Field	Type	Description
`createdNote`	array	Created notes (present on create)
`updatedNote`	object	Updated note (present on update)
`deletedNote`	object	Deleted note (present on delete)
`[].noteId`	integer	Note ID
`[].leadId`	integer	Associated lead ID
`[].updateTime`	integer	Epoch milliseconds of the change
`[].noteType`	string	`Manual`, `System`, or `AI`
`[].agentId`	integer	Agent user ID

10. Task

Triggered when a task is created, updated, finished, or deleted. Multiple action fields may appear in a single payload.

{
  "teamId": 123456,
  "listId": 10,
  "createdTask": [
    { "taskId": 101, "leadId": 456, "updateTime": 1736935800000 }
  ],
  "updatedTask": [
    { "taskId": 102, "leadId": 457, "updateTime": 1736935860000 }
  ],
  "finishedTask": [
    { "taskId": 103, "leadId": 458, "updateTime": 1736935920000 }
  ],
  "deletedTask": [
    { "taskId": 104, "leadId": 459, "updateTime": 1736935980000 }
  ]
}

Field	Type	Description
`createdTask`	array	Created tasks (present on create)
`updatedTask`	array	Updated tasks (present on update)
`finishedTask`	array	Finished tasks (present on finish)
`deletedTask`	array	Deleted tasks (present on delete)
`[].taskId`	integer	Task ID
`[].leadId`	integer	Associated lead ID
`[].updateTime`	integer	Epoch milliseconds of the change

11. Appointment

Triggered when an appointment is created, updated, finished, or deleted. Multiple action fields may appear in a single payload.

{
  "teamId": 123456,
  "listId": 11,
  "createdAppt": [
    { "apptId": 101, "leadId": 456, "updateTime": 1736935800000 }
  ],
  "updatedAppt": [
    { "apptId": 102, "leadId": 457, "updateTime": 1736935860000 }
  ],
  "finishedAppt": [
    { "apptId": 103, "leadId": 458, "updateTime": 1736935920000 }
  ],
  "deletedAppt": [
    { "apptId": 104, "leadId": 459, "updateTime": 1736935980000 }
  ]
}

Field	Type	Description
`createdAppt`	array	Created appointments (present on create)
`updatedAppt`	array	Updated appointments (present on update)
`finishedAppt`	array	Finished appointments (present on finish)
`deletedAppt`	array	Deleted appointments (present on delete)
`[].apptId`	integer	Appointment ID
`[].leadId`	integer	Associated lead ID
`[].updateTime`	integer	Epoch milliseconds of the change

12. Pipeline Change

Triggered when a lead’s pipeline stage changes.

{
  "teamId": 123456,
  "listId": 12,
  "updatedLeadstage": [
    {
      "leadId": 456,
      "updateTime": 1736935800000,
      "changeInfo": {
        "oldstage": "New Lead",
        "newstage": "Contacted"
      }
    }
  ]
}

Field	Type	Description
`updatedLeadstage`	array	Pipeline stage change records
`[].leadId`	integer	Lead ID
`[].updateTime`	integer	Epoch milliseconds of the stage change
`[].changeInfo.oldstage`	string	Previous pipeline stage name
`[].changeInfo.newstage`	string	New pipeline stage name

Best practices

Respond immediately. Return a 2xx before processing and move your logic to a background job. Lofty limits concurrent deliveries per endpoint, so a slow handler directly reduces your delivery throughput — at high event volume, synchronous processing is the most common cause of delayed webhooks. Handle duplicates. The same event may be delivered more than once (for example, when a timeout swallowed your response). Deduplicate with the Lofty-Webhook-Id header — it is stable across retries of the same event. Don’t assume ordering. Retries mean an older event can arrive after a newer one. Order by the updateTime field inside the payload, not by arrival time. Acknowledge pings. Return 2xx to {"eventType": "ping"} probes — they are how a disabled subscription recovers automatically. Decommission cleanly. When you shut an endpoint down for good, return 410 Gone so Lofty stops delivering immediately instead of retrying against a dead URL. Validate payloads. Check that listId matches your expected event type before processing. Use HTTPS. Plain HTTP endpoints are rejected.

Use ngrok during development to tunnel webhooks to your local machine.

Example receiver

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhooks/lofty', (req, res) => {
  res.sendStatus(200); // ack first — this also covers ping probes
  if (req.body.eventType === 'ping') return;
  const { listId, events } = req.body;
  processEvents(listId, events).catch(console.error);
});

async function processEvents(listId, events) {
  for (const event of events) {
    console.log(`Event type ${listId}:`, event);
  }
}

app.listen(3000);

Resolving communication events to full records

After receiving a Call / Email / Text webhook, fetch the full record by passing the event’s timelineId as the communicationId path parameter of the v2 by-ID endpoint:

Webhook event	Lookup endpoint	Response
Call	`GET /v2.0/communication/call/{communicationId}`	`CallResponse`
Email	`GET /v2.0/communication/email/{communicationId}`	`EmailResponse`
Text	`GET /v2.0/communication/text/{communicationId}`	`TextResponse`

timelineId is the recommended round-trip key — it always points to the same lead_timeline row regardless of whether the event is MANUAL or LOGGED. The legacy callId / emailId / textId fields still ship for backward compatibility, but their underlying record changes between the two communicationType values, so they are not safe to pass to the v2 by-ID endpoints.

All IDs in webhook payloads are 64-bit integers. JavaScript clients must handle them carefully — see JS / TS Integration.

Get Started

Authentication

Core Concepts

Guides

Lofty CLI

MCP Server

Manage subscriptions

Delivery timing

Retries and failure handling

Retry schedule

Response handling

Idempotent delivery

Endpoint health and automatic disabling

Health probes and automatic recovery

Notification recipients

Assignment-based delivery — `permissionMode: 0` (default)

Ownership-based delivery — `permissionMode: 1`

Common fields

Event types

Event payloads

1. Agent Info

2. Lead Info

3. Lead Activity

4. Listing Alert

5. Transaction

6. Call

7. Email

8. Text

9. Note

10. Task

11. Appointment

12. Pipeline Change

Best practices

Example receiver

Resolving communication events to full records

​Subscribe

​Manage subscriptions

​Delivery timing

​Retries and failure handling

​Retry schedule

​Response handling

​Idempotent delivery

​Endpoint health and automatic disabling

​Health probes and automatic recovery

​Notification recipients

​Assignment-based delivery — permissionMode: 0 (default)

​Ownership-based delivery — permissionMode: 1

​Common fields

​Event types

​Event payloads

​1. Agent Info

​2. Lead Info

​3. Lead Activity

​4. Listing Alert

​5. Transaction

​6. Call

​7. Email

​8. Text

​9. Note

​10. Task

​11. Appointment

​12. Pipeline Change

​Best practices

​Example receiver

​Resolving communication events to full records

Subscribe

Manage subscriptions

Delivery timing

Retries and failure handling

Retry schedule

Response handling

Idempotent delivery

Endpoint health and automatic disabling

Health probes and automatic recovery

Notification recipients

Assignment-based delivery — `permissionMode: 0` (default)

Ownership-based delivery — `permissionMode: 1`

Common fields

Event types

Event payloads

1. Agent Info

2. Lead Info

3. Lead Activity

4. Listing Alert

5. Transaction

6. Call

7. Email

8. Text

9. Note

10. Task

11. Appointment

12. Pipeline Change

Best practices

Example receiver

Resolving communication events to full records