Webhooks API reference

Lodgestory can notify your systems the moment something happens in your workspace — a message arrives, a ticket changes hands, a campaign finishes, a call ends. You register an HTTPS endpoint, pick the events you care about, and Lodgestory POSTs a signed JSON notification to it for every matching event.

This page is the developer contract: the envelope every delivery shares, the headers and signature scheme, retry behaviour, the complete event catalogue, and the exact payload of every event type. For the product walkthrough (creating endpoints in the UI, delivery log, test and replay), see the Webhooks settings guide.

At a glance

The envelope

Every delivery — regardless of event type — is a POST with this JSON body:

{
  "id": "0c6532a2-8e2a-4b6e-9d5e-1f9b1a7e4c11",
  "event": "message.received",
  "api_version": "2026-05-01",
  "occurred_at": "2026-08-02T10:14:02.000Z",
  "organisation_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "object": "message",
    "message": {
      "…": "the full object — see the per-event reference below"
    }
  }
}

Delivery semantics

• At-least-once. The same delivery can occasionally arrive twice (for example, if your endpoint responds slowly and a retry overlaps). Make your handler idempotent using id / X-Webhook-Id.
• No ordering guarantee. Deliveries are made in parallel and retried independently, so events can arrive out of order. Sequence with occurred_at and the timestamps inside each object, not arrival order.
• Snapshots, not live reads. The payload reflects the record at the moment the event fired. If you need the current state later, read it from the API.
• Per-endpoint filtering. An endpoint only receives the event types it subscribes to.

Delivery headers

If you configured custom headers on the endpoint (for example, an Authorization header for your own gateway), they are sent on every delivery in addition to the above.

Verifying the signature

Every delivery is signed with the endpoint's signing secret (shown when you create the endpoint; view or rotate it any time). The signature is an HMAC-SHA256 over the timestamp header and the raw request body, joined by a dot:

signature = "sha256=" + hex( HMAC_SHA256( secret, "<X-Webhook-Timestamp>.<raw body>" ) )

To verify: recompute it from the exact bytes you received and compare against X-Webhook-Signature using a constant-time comparison. Always use the raw, unparsed body — re-serializing the JSON changes the bytes and breaks the check.

Node.js

import crypto from 'crypto';

function isValidDelivery(req, secret) {
  const timestamp = req.headers['x-webhook-timestamp'];
  const signature = req.headers['x-webhook-signature']; // "sha256=…"
  const expected =
    'sha256=' +
    crypto
      .createHmac('sha256', secret)
      .update(`${timestamp}.${req.rawBody}`) // the exact bytes received
      .digest('hex');
  return (
    signature?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  );
}

Python

import hashlib, hmac

def is_valid_delivery(headers, raw_body: bytes, secret: str) -> bool:
    timestamp = headers["X-Webhook-Timestamp"]
    signature = headers.get("X-Webhook-Signature", "")
    expected = "sha256=" + hmac.new(
        secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Replay protection. The timestamp is part of the signed input, so an attacker can't re-sign an old body with a fresh time. Reject deliveries whose X-Webhook-Timestamp is older than a few minutes (5 minutes is a sensible tolerance — remember that retries of a failed delivery are re-signed with a fresh timestamp on each attempt).

Rotation. After rotating a secret, deliveries are signed with the new secret immediately. If you need zero-gap rotation, verify against both secrets for a short window on your side.

Responding, retries, and automatic pause

• Respond with any 2xx status to acknowledge. Anything else — including a timeout — counts as a failure.
• Each attempt waits up to 10 seconds for your response. Acknowledge fast and process asynchronously; the response body is ignored (only the first 1,000 bytes are kept for the delivery log).
• Failed deliveries are retried automatically: up to 6 attempts with roughly doubling delays, spread over about 3 minutes.
• If an endpoint keeps failing — 15 consecutive events exhausting all their retries — it is paused automatically and stops receiving traffic. Fix your endpoint, then re-enable it (re-enabling resets the failure count). Any successful delivery also resets the count.
• Every attempt is recorded in the delivery log (kept for 30 days) with status, response code, and attempt count. You can redeliver any logged delivery on demand; the replay carries the original payload with a fresh delivery ID.
• Automatic pause and redelivery apply to endpoints (subscriptions) only. Automation API calls use the same retry schedule and the same 10-second timeout, but a failing target never pauses anything and cannot be redelivered from the webhooks screen — re-run the automation instead.

Chat identifiers — read this once

Two different chat identifiers appear across payloads, and mixing them up is the most common integration bug:

• chat_id on ticket, chat_state, call, and goal_milestone payloads is the conversation ID (a UUID) — the same ID the Lodgestory API uses for chat endpoints.
• chat_id on message payloads is the channel-level thread ID (for example [email protected] on WhatsApp) — the ID of the thread on the channel itself.
• goal_milestone carries both: chat_id (conversation UUID) and channel_chat_id (channel thread ID), so you can join goal events to either stream.
• instagram_comment carries both too: chat_id is the conversation UUID of the post's comment thread (every comment on the same post shares it) and channel_chat_id is the thread's channel-level ID, ig_media:<media id>. Comments never appear in message payloads — they have their own event.

Supported events

Call events fire for calls on Lodgestory Voice numbers. Calls carried by third-party telephony providers connected to your workspace don't produce webhooks.

Event payloads

Each section below documents one data.object type: the events that use it, every field, and a full example. All field names are snake_case; timestamps are ISO 8601 strings; any field can be null when the underlying value is absent.

message — message.sent, message.received

One payload per message, on every channel. direction always matches the event: inbound for message.received, outbound for message.sent. Internal system entries (join notes, automated markers) never fire message events. Campaign sends fire one message.sent per recipient. Instagram comments aren't messages — they arrive as instagram.comment.received (see instagram_comment below); a private reply sent from a comment is a real DM, though, and fires message.sent on the commenter's chat.

{
  "id": "wamid.HBgMOTE5OTk5OTk5OTk5FQIAEhgg…",
  "chat_id": "[email protected]",
  "channel_id": "3f6f6c53-9d2a-4a0e-8f2b-6b7e5a1c2d3e",
  "channel_type": "whatsapp",
  "direction": "inbound",
  "type": "text",
  "text": "Is breakfast included with the deluxe room?",
  "media_uri": null,
  "status": null,
  "from_name": "John Doe",
  "from_number": "+919999999999",
  "reply_to_message_id": null,
  "agent_id": null,
  "via": null,
  "timestamp": "2026-08-02T10:14:02.000Z"
}

message_status — message.status_updated

Delivery-receipt updates for messages you sent, on channels that report them (WhatsApp Official today). Expect one event per status transition — a read message typically produces SENT → DELIVERED → READ. Failures (FAILED) include messages the provider accepted but could not deliver.

{
  "message_id": "wamid.HBgMOTE5OTk5OTk5OTk5FQIAEhgg…",
  "chat_id": null,
  "channel_id": "3f6f6c53-9d2a-4a0e-8f2b-6b7e5a1c2d3e",
  "channel_type": "whatsapp",
  "status": "READ",
  "timestamp": "2026-08-02T10:15:40.000Z"
}

template — template.created, template.status_updated, template.quality_updated

WhatsApp template lifecycle. template.created fires when the template is submitted (status is typically the initial review state); template.status_updated fires whenever WhatsApp's review status changes; template.quality_updated fires when WhatsApp's quality rating for an approved template moves (GREEN / YELLOW / RED / UNKNOWN), with the prior score in previous_attributes.qualityScore.

{
  "id": "1189312045678901",
  "name": "booking_confirmation",
  "language": "en",
  "category": "UTILITY",
  "status": "APPROVED",
  "rejected_reason": null,
  "quality_score": null
}

ticket — ticket.created, ticket.status_changed, ticket.assigned

The full ticket record. ticket.status_changed fires only on a genuine open ⇄ resolved transition, with previous_attributes.status. ticket.assigned fires whenever the assignee changes, with previous_attributes.assigned_to_user_id (the previous assignee, or null if it was unassigned). When a member is removed from the organisation, each of their open tickets fires ticket.assigned with assigned_to_user_id: null.

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "ticket_number": 42,
  "chat_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "call_log_id": null,
  "customer_phone": "+919999999999",
  "customer_email": null,
  "status": "resolved",
  "resolved": true,
  "priority": "HIGH_PRIORITY",
  "assigned_to_user_id": "8a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "created_by_user_id": "77fa1329-5f0b-4c2d-9e3a-1b2c3d4e5f60",
  "issue": { "Room Service": ["Late delivery"] },
  "fields": { "field_room_no": 204, "field_category": "Refund" },
  "remarks": "Guest called twice; comped breakfast.",
  "created_at": "2026-08-01T09:00:00.000Z",
  "updated_at": "2026-08-02T11:02:00.000Z"
}

With, on ticket.status_changed:

"previous_attributes": { "status": "open" }

contact — contact.created

{
  "id": "b7e23ec2-9054-4c3f-a1de-2f4b8c6d0e12",
  "name": "John Doe",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "9999999999",
  "country_code": "+91",
  "email": null,
  "origin": "MANUAL",
  "created_at": "2026-08-02T10:14:05.000Z"
}

Treat origin: "DISPOSITION" and origin: "BOT_JOURNEY" contacts as already mid-conversation, not as new leads: a welcome sequence, a "thanks for reaching out" message, or a lead-scoring hook keyed on contact.created should skip them. The field is stamped on the event, not stored on the contact.

chat_resolution — chat.resolved

Fires when a conversation is resolved (closed), and again when it reopens. Resolution comes from an agent's explicit Resolve & Close, a bot journey's AI agent closing it after its goodbye, or a workflow finishing when the organisation's Chat closing switch (or the workflow's own closing rule) says finishing also resolves the chat. Reopening comes from an admin or assignee flipping it back, a new customer message auto-reopening it, the AI agent undoing its own close when a customer message raced it, or the chat's workflow being restarted. resolved tells you the direction, via tells you the cause, and previous_attributes carries the prior flag.

{
  "chat_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "channel_chat_id": "919812345678",
  "channel_id": "3f8e2a10-9b7c-4d2e-8f01-5a6b7c8d9e0f",
  "resolved": true,
  "resolved_at": "2026-08-02T12:30:00.000Z",
  "resolved_by_user_id": "8a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "via": "AGENT"
}

With:

"previous_attributes": { "resolved": false }

A workflow-driven resolution carries the same shape with "via": "WORKFLOW"; the finishing move itself arrives separately as chat.state_changed with is_final: true. Two cases produce no chat.resolved even though a workflow finished: another workflow on the chat is still active (the chat stays open), or the agent unticked Also mark chat as resolved on that close.

chat_assignment — chat.assigned

Fires when a conversation's primary assignee is set or changed — the moment a human takes ownership: a bot journey hands the chat to an agent or team, someone assigns it manually in the CRM, or an automation's assign-chat action runs. It does not fire for secondary-assignee additions, for deassignments, or for the administrative primary re-election that runs when a team member is removed from the workspace.

{
  "chat_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "channel_chat_id": "919812345678",
  "channel_id": "3f8e2a10-9b7c-4d2e-8f01-5a6b7c8d9e0f",
  "chat_name": "Asha Patel",
  "assignee_user_id": "8a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "assignee_name": "Priya Sharma",
  "assignee_email": "[email protected]",
  "previous_assignee_user_id": null,
  "assigned_by_user_id": "5c6d7e8f-9a0b-1c2d-3e4f-5a6b7c8d9e0f"
}

With:

"previous_attributes": { "assignee_user_id": null }

chat_team_assignment — chat.team_assigned

Fires when one or more teams are newly attached to a conversation — the routing moment. It fires even when no individual owner gets selected (an off-hours transfer where nobody on the team is available attaches the team but picks nobody — chat.assigned then never fires, and this event is the only signal). Only the newly attached teams are reported; teams already on the conversation are not repeated.

It is also the signal for capacity overflow. Organisations can cap each advisor's open chats; when every eligible member of the routed team is at their cap (or offline), the team is attached, nobody is picked, and the chat waits in the team's queue with no owner. chat.assigned follows only when someone claims it, an admin assigns it, or an automation pulls it — so a chat.team_assigned with no chat.assigned after a few minutes is the "chat is queueing" condition worth alerting on.

{
  "chat_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "channel_chat_id": "919812345678",
  "channel_id": "3f8e2a10-9b7c-4d2e-8f01-5a6b7c8d9e0f",
  "chat_name": "Asha Patel",
  "team_ids": ["7b2e4c66-1a2b-4c3d-9e0f-a1b2c3d4e5f6"],
  "team_names": ["Reservations"],
  "assigned_by_user_id": "5c6d7e8f-9a0b-1c2d-3e4f-5a6b7c8d9e0f"
}

chat_workflow — chat.workflow_started

Fires when a workflow (lifecycle-stage set) is attached to a conversation — the moment it enters the workflow. Stage transitions and completion then flow as chat.state_changed.

{
  "chat_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "state_machine_id": "0d47ac10-58cc-4372-a567-0e02b2c3d479",
  "state_machine_name": "Guest journey",
  "state_id": "node-1",
  "state_name": "New",
  "is_final": false,
  "attached_by_user_id": null,
  "trigger": "AUTO",
  "attached_at": "2026-08-02T12:30:00.000Z"
}

chat_state — chat.state_changed

Fires when a conversation moves between workflow lifecycle stages, including moving into a final stage and restarting a finished workflow. previous_attributes carries the stage it moved from.

{
  "chat_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "state_machine_id": "0d47ac10-58cc-4372-a567-0e02b2c3d479",
  "state_machine_name": "Guest journey",
  "state_id": "node-3",
  "state_name": "Awaiting Guest",
  "is_final": false,
  "responsible_user_id": "8a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "remarks": "Waiting on guest confirmation",
  "changed_at": "2026-08-02T12:30:00.000Z"
}

With:

"previous_attributes": { "state_id": "node-2", "state_name": "In Progress" }

campaign — campaign.created, campaign.completed

campaign.created fires when the campaign is created — from the builder, the partner API, or an AI assistant. Its audience is usually still being prepared at that point: status is SCHEDULED and total_messages is the expected count. campaign.completed fires exactly once when the campaign ends: status is COMPLETED, or FAILED when not a single message went out — including when the audience couldn't be prepared (nobody in it could be messaged on the channel, or its segment was deleted first). A cancelled campaign never fires campaign.completed. The counters are final on the completion event.

audience

prepare_stats — counts, each present only when it is above zero: read (audience entries processed), queued (messages scheduled), and the entries skipped — duplicate (the same chat twice), invalidPhone, invalidEmail, otherChannel (a chat on another channel), notFound (a chat or contact that no longer exists), invalidRow (an unreadable entry).

{
  "id": "5f7d8e9a-0b1c-2d3e-4f50-617283940a5b",
  "name": "August offers",
  "status": "COMPLETED",
  "channel_id": "3f6f6c53-9d2a-4a0e-8f2b-6b7e5a1c2d3e",
  "total_messages": 1200,
  "completed_messages": 1187,
  "failed_messages": 13,
  "delivered_messages": 1160,
  "read_messages": 902,
  "replied_messages": 141,
  "clicked_messages": 0,
  "message_type": "TEMPLATE",
  "schedule_at": "2026-08-01T09:30:00.000Z",
  "audience": {
    "kind": "segment",
    "segment_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "segment_name": "Goa guests — summer 2026",
    "source_campaign_id": null,
    "retarget_segment": null,
    "frozen_count": 1240
  },
  "prepare_stats": {
    "read": 1240,
    "queued": 1200,
    "duplicate": 12,
    "invalidPhone": 28
  },
  "created_at": "2026-08-01T08:00:00.000Z"
}

flow_response — flow.response_received

A customer completed a WhatsApp Flow. Every flow send carries a unique token minted by Lodgestory, so each response arrives already correlated: source says what sent the flow, and campaign_id is set for campaign sends. response is the answers object exactly as the flow's submit defined it (field names come from the flow's components); photo/document answers reference uploaded media ids.

{
  "id": "9a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "flow_id": "662739091060588",
  "chat_id": "919888877766",
  "channel_id": "3f6f6c53-9d2a-4a0e-8f2b-6b7e5a1c2d3e",
  "source": "journey",
  "campaign_id": null,
  "response": {
    "check_in": "2026-09-12",
    "party_size": "4",
    "room_preference": "sea_view"
  },
  "sent_at": "2026-08-15T09:12:44.000Z",
  "responded_at": "2026-08-15T09:14:02.000Z"
}

channel — channel.connected, channel.disconnected

A connected messaging channel changed availability. The payload never includes channel credentials or tokens.

{
  "id": "3f6f6c53-9d2a-4a0e-8f2b-6b7e5a1c2d3e",
  "channel_type": "whatsapp",
  "name": "104857623456789",
  "phone_number": "+919888877766",
  "connected": true
}

push_device — push.device_registered, push.device_identified, push.device_invalidated

A device of one of your push apps (see Push notifications API). Never carries the provider token.

{
  "id": "1d5e…",
  "channel_id": "c1d2e3f4-…",
  "contact_id": "33333333-…",
  "external_user_id": "u_4421",
  "platform": "android",
  "provider": "fcm",
  "app_version": "1.0.3",
  "os_version": "15",
  "locale": "en-IN",
  "timezone": "Asia/Kolkata",
  "notifications_enabled": true,
  "marketing_opt_in": true,
  "status": "ACTIVE",
  "invalid_reason": null,
  "last_seen_at": "2026-10-21T09:58:12.000Z",
  "created_at": "2026-10-21T09:58:12.000Z"
}

status is ACTIVE, UNSUBSCRIBED or INVALID (invalid_reason = Apple's / Google's reason, or stale after 180 days unseen). contact_id is null until identified. Push sends themselves raise no message.* events — they are not chat messages. Follow one with GET /api/wp-crm/push/{organisationId}/messages/{id} (per-device sent / delivered / opened), and a push campaign through its counters and campaign.completed.

group — group.created

A WhatsApp group appeared on one of your WhatsApp Official channels. Group creation via POST /api/wp-crm/groups/:orgId is asynchronous — the create call returns only a requestId; this event completes the loop by delivering the group's chat_id. Match on request_id to correlate. Groups created outside the API (e.g. from the connected phone) also fire it, with request_id: null.

The chat_id is a normal conversation ID: it works with the messaging, chats, and chat-assignment APIs, so you can immediately message the group and assign agents to it.

{
  "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "chat_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "group_id": "120363043968812345",
  "channel_id": "3f6f6c53-9d2a-4a0e-8f2b-6b7e5a1c2d3e",
  "subject": "Villa Amara — Guest Group",
  "description": "Concierge support for your stay, 24×7.",
  "invite_link": "https://chat.whatsapp.com/JZk1aB2cD3e",
  "join_approval_mode": true,
  "request_id": "1234567890",
  "created_at": "2026-08-15T09:12:40.000Z"
}

instagram_comment — instagram.comment.received

Someone commented on one of your Instagram posts, reels or ads. Fires for Instagram channels that have Comments in inbox switched on (Connections), once per comment — replies to comments included (is_reply, with parent_id). Comments posted by your own account never fire it, and neither do public replies sent from Lodgestory. Comments live in the post's comment thread in the inbox: chat_id is that thread's conversation ID, shared by every comment on the same post. The media block describes the post the comment is on.

{
  "id": "17895695668004550",
  "text": "Is the pool villa available in June?",
  "username": "jane_doe",
  "from_id": "1234567890123456",
  "is_reply": false,
  "parent_id": null,
  "is_own": false,
  "hidden": false,
  "created_at": "2026-08-28T10:14:02.000Z",
  "chat_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "channel_chat_id": "ig_media:17900000000000000",
  "channel_id": "3f6f6c53-9d2a-4a0e-8f2b-6b7e5a1c2d3e",
  "channel_type": "instagram",
  "media": {
    "id": "17900000000000000",
    "product_type": "REELS",
    "media_type": "VIDEO",
    "caption": "Monsoon mornings at Villa Amara 🌧️ Book your June escape.",
    "permalink": "https://www.instagram.com/reel/C9xYzAbCdEf/",
    "thumbnail_url": "https://scontent.cdninstagram.com/v/t51.../thumb.jpg",
    "published_at": "2026-08-25T07:30:00.000Z",
    "is_ad": false,
    "ad_id": null,
    "ad_title": null,
    "original_media_id": null
  }
}

A private reply sent from a comment — in the inbox, by an automation, or via the API — is a real Instagram DM, so it fires message.sent on the commenter's chat, not on the thread.

call — call.answered, call.completed, call.missed, call.recording_available, call.transcript_available

All five events share this payload — a snapshot of the call record. On call.recording_available the payload always has recording_available: true; on call.transcript_available it always has has_transcript: true. Recording/transcript events can arrive minutes after call.completed for the same call (id ties them together). Fires for Lodgestory Voice numbers only.

call.answered fires while the call is still live, the moment it is picked up: an agent answers an inbound call (browser softphone, desk phone or their own phone), or the customer answers an agent's outbound call or an API click-to-call — on a connect call, when the two people are connected. Use it to pop the customer's record on the agent's screen — look up customer_number, and route the pop by agent.email / agent.user_id. On this event status is IN_PROGRESS; the fields only known at hangup are null or 0 (hangup_cause, ended_by, ended_via, ended_at, the durations, recording and transcript flags); and chat_id is usually null, because calls are linked to a conversation at hangup. It is sent once per answering agent — after a transfer it is sent again naming the new agent (an outbound call's part after the hand-over arrives as its own record with continuation_of set). It never arrives after call.completed for the same call; if a delayed pickup is processed after the hangup, it is dropped.

{
  "id": "0b1f2e3d-4c5b-6a79-8897-a6b5c4d3e2f1",
  "direction": "INBOUND",
  "status": "NO_ANSWER",
  "caller_number": "+919999999999",
  "called_number": "+918888877766",
  "caller_id": "+919999999999",
  "hangup_cause": "NO_ANSWER",
  "agent_user_id": null,
  "missed_agents": [
    { "user_id": "8a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9", "name": "Asha Rao", "number": "1001" },
    { "user_id": null, "name": null, "number": "1004" }
  ],
  "agent_offers": [
    {
      "user_id": "8a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
      "name": "Asha Rao",
      "number": "1001",
      "via": "queue",
      "department_id": "0796d4bf-353d-4886-aca6-dc27969dd5ca",
      "offers": 2,
      "declined": 0,
      "no_answer": 2,
      "busy": 0,
      "unreachable": 0,
      "outcome": "no_answer",
      "device": "softphone",
      "while_offline": false,
      "first_offered_at": "2026-08-02T14:05:12.000Z",
      "last_offered_at": "2026-08-02T14:05:30.000Z"
    },
    {
      "user_id": null,
      "name": null,
      "number": "1004",
      "via": "queue",
      "department_id": "0796d4bf-353d-4886-aca6-dc27969dd5ca",
      "offers": 1,
      "declined": 0,
      "no_answer": 0,
      "busy": 0,
      "unreachable": 1,
      "outcome": "unreachable",
      "device": null,
      "while_offline": false,
      "first_offered_at": "2026-08-02T14:05:12.000Z",
      "last_offered_at": "2026-08-02T14:05:12.000Z"
    }
  ],
  "chat_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "duration_total_sec": 32,
  "duration_talk_sec": 0,
  "duration_ring_sec": 28,
  "recording_available": false,
  "has_transcript": false,
  "custom_identifier": null,
  "transfers": [],
  "continuation_of": null,
  "department": {
    "id": "0796d4bf-353d-4886-aca6-dc27969dd5ca",
    "name": "Sales",
    "via": "route",
    "at": "2026-08-02T14:05:12.000Z",
    "result": "timeout",
    "wait_seconds": 30
  },
  "departments": [
    {
      "id": "0796d4bf-353d-4886-aca6-dc27969dd5ca",
      "name": "Sales",
      "via": "route",
      "at": "2026-08-02T14:05:12.000Z",
      "result": "timeout",
      "left_at": "2026-08-02T14:05:42.000Z",
      "wait_seconds": 30,
      "sticky": false
    }
  ],
  "business_hours": {
    "schedule_id": "7d2c1b0a-5e4f-4a3b-9c8d-1f2e3d4c5b6a",
    "schedule_name": "Front desk hours",
    "state": "open",
    "is_open": true,
    "after_hours": false,
    "day_name": null,
    "label": null,
    "at": "2026-08-02T14:05:10.000Z"
  },
  "initiated_at": "2026-08-02T14:05:10.000Z",
  "answered_at": null,
  "ended_at": "2026-08-02T14:05:42.000Z"
}

A call.missed for a caller who rang on a holiday and heard the holiday greeting (abridged):

{
  "id": "9e8d7c6b-5a49-4382-a716-05f4e3d2c1b0",
  "direction": "INBOUND",
  "status": "NO_ANSWER",
  "caller_number": "+919999999999",
  "called_number": "+918888877766",
  "customer_number": "+919999999999",
  "agent_user_id": null,
  "missed_agents": null,
  "department": null,
  "departments": [],
  "business_hours": {
    "schedule_id": "7d2c1b0a-5e4f-4a3b-9c8d-1f2e3d4c5b6a",
    "schedule_name": "Front desk hours",
    "state": "holiday",
    "is_open": false,
    "after_hours": true,
    "day_name": "Diwali",
    "label": null,
    "at": "2026-11-08T06:30:02.000Z"
  },
  "channel": "pstn",
  "duration_talk_sec": 0,
  "initiated_at": "2026-11-08T06:30:01.000Z",
  "answered_at": null,
  "ended_at": "2026-11-08T06:30:14.000Z"
}

A call.answered for an inbound call (abridged):

{
  "id": "5c7d8e9f-0a1b-4c2d-9e3f-4a5b6c7d8e9f",
  "direction": "INBOUND",
  "status": "IN_PROGRESS",
  "caller_number": "+919999999999",
  "called_number": "+918888877766",
  "customer_number": "+919999999999",
  "hangup_cause": null,
  "ended_by": null,
  "agent_user_id": "8a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "agent": {
    "user_id": "8a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
    "name": "Asha Rao",
    "email": "[email protected]"
  },
  "department": { "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876", "name": "Sales", "via": "route", "at": "2026-08-02T14:05:02.000Z", "result": "answered", "wait_seconds": 6 },
  "channel": "pstn",
  "chat_id": null,
  "duration_total_sec": null,
  "duration_talk_sec": null,
  "custom_identifier": null,
  "initiated_at": "2026-08-02T14:05:00.000Z",
  "answered_at": "2026-08-02T14:05:09.000Z",
  "ended_at": null
}

A WhatsApp call's channel fields:

"channel": "whatsapp",
"whatsapp": {
  "direction": "user_initiated",
  "call_id": "wacid.HBgMOTE5ODc2NTQzMjEwFQIAEhgg",
  "user_id": null,
  "business_number": "+918888877766",
  "wa_id": "919999999999"
}

A transferred call's transfers entry:

"transfers": [
  {
    "transfer_id": "5f0c8c1e-2a3b-4c5d-9e6f-7a8b9c0d1e2f",
    "at": "2026-09-13T10:12:04.000Z",
    "mode": "consult",
    "by_user_id": "8a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
    "by_supervisor": false,
    "from_user_id": "8a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
    "to": { "type": "agent", "user_id": "c4d5e6f7-8091-42a3-b4c5-d6e7f8091a2b", "name": "Meera Iyer", "number": null },
    "outcome": "completed",
    "fail_cause": null,
    "resolution": null,
    "queue_result": null,
    "consult_seconds": 18,
    "completed_at": "2026-09-13T10:12:41.000Z"
  }
]

A call.missed for a connect call where customer 2 did not answer (abridged):

{
  "id": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
  "direction": "OUTBOUND",
  "call_type": "connect",
  "status": "NO_ANSWER",
  "caller_number": "+919876543210",
  "called_number": "+919812345678",
  "caller_id": "+918888877766",
  "customer_number": "+919812345678",
  "agent_user_id": null,
  "agent": null,
  "connect": {
    "status": "NO_ANSWER",
    "from": { "number": "+919876543210", "status": "answered", "answered_at": "2026-10-24T09:30:06.000Z", "ring_seconds": 6, "hangup_cause": null },
    "to": { "number": "+919812345678", "status": "no_answer", "dialled_at": "2026-10-24T09:30:06.000Z", "answered_at": null, "ring_seconds": 30, "hangup_cause": "NO_ANSWER" },
    "ended_by_party": "system",
    "talk_seconds": 0,
    "max_duration_sec": 3600,
    "record": true
  },
  "duration_talk_sec": 0,
  "custom_identifier": "lmv-7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
  "reference": "booking-4821",
  "initiated_at": "2026-10-24T09:30:00.000Z",
  "answered_at": "2026-10-24T09:30:06.000Z",
  "ended_at": "2026-10-24T09:30:37.000Z"
}

survey_response — survey.response_submitted

Fires when a survey response is submitted (or a partial response is finalised). Sensitive request metadata (IPs, tokens, user agents) is never included.

{
  "id": "a1b2c3d4-e5f6-4071-8293-a4b5c6d7e8f9",
  "form_id": "0d47ac10-58cc-4372-a567-0e02b2c3d479",
  "form_name": "Post-stay CSAT",
  "form_slug": "post-stay-csat",
  "version_number": 3,
  "status": "COMPLETED",
  "source": "INVITE",
  "primary_score": 5,
  "primary_score_type": "STARS",
  "score_normalised": 1,
  "sentiment_band": "PROMOTER",
  "invite_id": "7b2e4c66-1a2b-4c3d-9e0f-a1b2c3d4e5f6",
  "contact_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "external_customer_ref": null,
  "interaction_id": "8a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "interaction_type": "CALL",
  "interaction_at": "2026-08-02T12:00:00.000Z",
  "channel": "WHATSAPP_OFFICIAL",
  "agent_user_id": "5c6d7e8f-9a0b-1c2d-3e4f-5a6b7c8d9e0f",
  "team_id": null,
  "queue_id": null,
  "trigger_event": "call.completed",
  "metadata": null,
  "started_at": "2026-08-02T12:31:00.000Z",
  "responded_at": "2026-08-02T12:33:10.000Z",
  "time_to_complete_seconds": 130,
  "contact_consent": true,
  "consent_name": "Asha Patel",
  "consent_email": null,
  "consent_phone": "+919812345678",
  "answers": [
    {
      "node_id": "q-rating",
      "question_type": "STARS",
      "question_text": "How was your stay?",
      "scale_min": 1,
      "scale_max": 5,
      "numeric_value": 5,
      "text_value": null,
      "comment_text": "Lovely villa!",
      "selected_option_ids": null,
      "selected_option_labels": null
    }
  ]
}

goal_milestone — goal.milestone_reached

A live bot-journey conversation passed a Goal milestone. Carries the tracker values captured up to that point — ready to pipe conversions into your analytics or CRM. Fires for live conversations only; builder test-runs are excluded.

{
  "id": "9e8d7c6b-5a49-3827-1605-f4e3d2c1b0a9",
  "goal_id": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809",
  "goal_name": "Bookings",
  "milestone_id": "aa11bb22-cc33-dd44-ee55-ff6677889900",
  "milestone_name": "Booking confirmed",
  "journey_id": "journey-42",
  "chat_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "channel_chat_id": "[email protected]",
  "chat_name": "John Doe",
  "channel_id": "3f6f6c53-9d2a-4a0e-8f2b-6b7e5a1c2d3e",
  "tracker_values": { "Order_ID": "ORD-1042", "Room_Type": "Deluxe" },
  "recorded_at": "2026-08-02T09:15:00.000Z"
}

disposition — disposition.created

An advisor captured a disposition — the outcome form on a chat, a call, a booking, or a lead in the Agent Dialer. Fires once per capture. The id matching source_type is set: chat_id, call_id or booking_id — or lead_id for a LEAD outcome, which also carries call_id when the outcome was for a call. values is keyed by the template's field ids (the template's fields array, available from the dispositions API, maps ids to labels). Lodgestory's own Meta Ads Lead Signals consume the same event in-process.

{
  "id": "6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "source_type": "CHAT",
  "chat_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "call_id": null,
  "booking_id": null,
  "lead_id": null,
  "contact_id": "0b4d5c6e-7f80-4a91-b2c3-d4e5f6a7b8c9",
  "template_id": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
  "template_name": "Chat outcome",
  "values": { "outcome": "Booked", "booking_value": "18500" },
  "outcome_label": "Booked — 2 nights",
  "notes": null,
  "created_by_user_id": "5c9a1f2e-3b4d-4e6f-8a9b-0c1d2e3f4a5b",
  "created_at": "2026-09-04T09:15:00.000Z"
}

lead — lead.created, lead.assigned, lead.stage_changed, lead.track_moved, lead.sla_breached

A lead — one enquiry in a Track, pointing at a contact. Every lead event carries the same snapshot of the lead as it stood after the change; previous_attributes (see the catalogue) holds what changed, under the same field names. Captured details are under fields, keyed by the lead type's field ids. The dedupe fingerprint is never sent.

lead_attempt — lead.outcome_captured

One attempt on a lead and its outcome, with the lead embedded under lead (the same shape as above). Fires once per dial: an agent's saved outcome — or, for a paced call that nobody answered, the dialer's own report. lead.stage_changed covers where the lead ended up.

ai_request — ai_request.created, ai_request.answered, ai_request.replied

The Bot Journey AI agent raised a request for a person — a question for the team (kind QUESTION), a choice between options it proposed (CHOICE), or a change it may only make with a teammate's OK (APPROVAL) — and, later, the request was settled; in between, Kaylee may have replied to a teammate's ask-back about it. See the Kaylee console for how requests reach your team.

ai_request.created fires the moment the request is raised, before anyone is notified — turn_user_id is still null. ai_request.answered fires once it leaves PENDING for any reason, with previous_attributes.status PENDING: a person answered, approved or rejected it (resolved_via says from where), or Lodgestory closed it (resolved_via SYSTEM) — it expired, was auto-rejected because nobody answered, was withdrawn by the agent, was handled directly by a teammate who replied in the conversation, or was taken over from the console. Requests raised in builder test-runs fire none of these events.

ai_request.replied fires while the request is still PENDING, each time Kaylee replies to a teammate's ask-back — a question a teammate put to her about the request before deciding — or asks the customer about it first. The thread is in ask_backs, and the last entry is the one that changed: status ANSWERED carries her reply to the teammate (answered_by KAYLEE, or SYSTEM when she had to say she couldn't answer — the conversation had moved on); ASKED_CUSTOMER means she asked the customer one short question, and her reply to the teammate follows as another ai_request.replied once they answer. There are no previous_attributes: the request's own fields haven't changed. Up to three ask-backs per request, one open at a time; one still open when the request is settled is closed with it — ai_request.answered carries it as CLOSED.

Answer from your own systems with the AI requests API — POST /api/wp-crm/ai-requests/:organisationId/:id/answer for questions and choices, /approve or /reject for approvals, and /ask-back to put a question to Kaylee first (reference). The first answer wins, from any surface. For an approval, ai_request.answered is sent when the decision is made, while execution_status is still PENDING; the change runs right after, inside the conversation — read the request (GET …/:id) for DONE or FAILED.

ai_request.created — a change held for approval:

{
  "id": "6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c",
  "number": 1,
  "kind": "APPROVAL",
  "status": "PENDING",
  "stage": "TURN",
  "question": "May I call \"Issue refund\" with amount: 8400, booking_ref: LS-20931?",
  "customer_quote": "Please refund the 8,400 I paid for the extra night, we never used it.",
  "options": null,
  "action": {
    "source": "org_api",
    "tool": "Issue refund",
    "api_id": "2b7c1d9e-3f40-4a51-b62c-7d8e9f0a1b2c",
    "label": "call \"Issue refund\" with amount: 8400, booking_ref: LS-20931",
    "args": { "amount": 8400, "booking_ref": "LS-20931" }
  },
  "answer": null,
  "decision": null,
  "edited_args": null,
  "answer_verbatim": false,
  "resolved_via": null,
  "resolved_by_user_id": null,
  "resolved_at": null,
  "execution_status": "NONE",
  "ask_backs": [],
  "chat_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "channel_name": "WHATSAPP",
  "customer_label": "Sofia L.",
  "journey_id": "9c1e4b2a-7d3f-4e85-a6b0-1f2e3d4c5b6a",
  "agent_label": "Concierge AI",
  "target_team_id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
  "target_team_name": "Finance",
  "turn_user_id": null,
  "expires_at": "2026-10-10T14:05:00.000Z",
  "created_at": "2026-10-10T10:05:00.000Z",
  "updated_at": "2026-10-10T10:05:00.000Z"
}

ai_request.replied — Riya, whose turn it is, asked Kaylee back from the console before deciding, and Kaylee answered her (the request is unchanged; no previous_attributes):

{
  "id": "6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c",
  "number": 1,
  "kind": "APPROVAL",
  "status": "PENDING",
  "stage": "TURN",
  "question": "May I call \"Issue refund\" with amount: 8400, booking_ref: LS-20931?",
  "customer_quote": "Please refund the 8,400 I paid for the extra night, we never used it.",
  "options": null,
  "action": {
    "source": "org_api",
    "tool": "Issue refund",
    "api_id": "2b7c1d9e-3f40-4a51-b62c-7d8e9f0a1b2c",
    "label": "call \"Issue refund\" with amount: 8400, booking_ref: LS-20931",
    "args": { "amount": 8400, "booking_ref": "LS-20931" }
  },
  "answer": null,
  "decision": null,
  "edited_args": null,
  "answer_verbatim": false,
  "resolved_via": null,
  "resolved_by_user_id": null,
  "resolved_at": null,
  "execution_status": "NONE",
  "ask_backs": [
    {
      "number": 1,
      "question": "Did they check out a night early, or book an extra night they then didn't use?",
      "asked_by_user_id": "8a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
      "asked_via": "CONSOLE",
      "asked_at": "2026-10-10T10:06:10.000Z",
      "status": "ANSWERED",
      "answer": "They checked out a night early: Sofia wrote that they left on the 8th and the room stayed empty on the 9th. Whether the booking fee is refundable isn't in the conversation or my instructions.",
      "answered_at": "2026-10-10T10:06:25.000Z",
      "answered_by": "KAYLEE"
    }
  ],
  "chat_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "channel_name": "WHATSAPP",
  "customer_label": "Sofia L.",
  "journey_id": "9c1e4b2a-7d3f-4e85-a6b0-1f2e3d4c5b6a",
  "agent_label": "Concierge AI",
  "target_team_id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
  "target_team_name": "Finance",
  "turn_user_id": "8a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "expires_at": "2026-10-10T14:05:00.000Z",
  "created_at": "2026-10-10T10:05:00.000Z",
  "updated_at": "2026-10-10T10:06:25.000Z"
}

Had Kaylee needed to check with the customer first, the entry would have arrived as ASKED_CUSTOMER with her question to the customer in answer, followed by a second ai_request.replied with the entry ANSWERED once the customer replied.

ai_request.answered — the same request, approved with edits from the console (the change then runs with edited_args); the ask-back thread rides along:

{
  "id": "6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c",
  "number": 1,
  "kind": "APPROVAL",
  "status": "APPROVED",
  "stage": "DONE",
  "question": "May I call \"Issue refund\" with amount: 8400, booking_ref: LS-20931?",
  "customer_quote": "Please refund the 8,400 I paid for the extra night, we never used it.",
  "options": null,
  "action": {
    "source": "org_api",
    "tool": "Issue refund",
    "api_id": "2b7c1d9e-3f40-4a51-b62c-7d8e9f0a1b2c",
    "label": "call \"Issue refund\" with amount: 8400, booking_ref: LS-20931",
    "args": { "amount": 8400, "booking_ref": "LS-20931" }
  },
  "answer": null,
  "decision": "EDIT",
  "edited_args": { "amount": 8000, "booking_ref": "LS-20931" },
  "answer_verbatim": false,
  "resolved_via": "CONSOLE",
  "resolved_by_user_id": "8a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "resolved_at": "2026-10-10T10:08:40.000Z",
  "execution_status": "PENDING",
  "ask_backs": [
    {
      "number": 1,
      "question": "Did they check out a night early, or book an extra night they then didn't use?",
      "asked_by_user_id": "8a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
      "asked_via": "CONSOLE",
      "asked_at": "2026-10-10T10:06:10.000Z",
      "status": "ANSWERED",
      "answer": "They checked out a night early: Sofia wrote that they left on the 8th and the room stayed empty on the 9th. Whether the booking fee is refundable isn't in the conversation or my instructions.",
      "answered_at": "2026-10-10T10:06:25.000Z",
      "answered_by": "KAYLEE"
    }
  ],
  "chat_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "channel_name": "WHATSAPP",
  "customer_label": "Sofia L.",
  "journey_id": "9c1e4b2a-7d3f-4e85-a6b0-1f2e3d4c5b6a",
  "agent_label": "Concierge AI",
  "target_team_id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
  "target_team_name": "Finance",
  "turn_user_id": "8a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "expires_at": "2026-10-10T14:05:00.000Z",
  "created_at": "2026-10-10T10:05:00.000Z",
  "updated_at": "2026-10-10T10:08:40.000Z"
}

With:

"previous_attributes": { "status": "PENDING" }

A question answered by phone looks the same with kind QUESTION, status ANSWERED, the spoken answer transcribed in answer, resolved_via PHONE and action null.

member — member.removed

A team member was removed from the organisation. Their open chats and tickets are unassigned as part of removal — the counts tell you how many, and each unassigned ticket also fires its own ticket.assigned event (new assignee null), so you can reconcile either way.

{
  "user_id": "8a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "email": "[email protected]",
  "first_name": "Asha",
  "last_name": "Rao",
  "organisation_id": "550e8400-e29b-41d4-a716-446655440000",
  "removed_roles": ["CRM_USER"],
  "unassigned_chats": 4,
  "unassigned_tickets": 2,
  "removed_at": "2026-08-02T16:20:00.000Z"
}

test — webhook.test

Sent only when you trigger Send test on an endpoint. It is delivered, signed, retried, and logged exactly like a real event — use it to verify your signature check end to end. It ignores the endpoint's event selection and cannot be subscribed to.

{
  "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
  "event": "webhook.test",
  "api_version": "2026-05-01",
  "occurred_at": "2026-08-02T17:00:00.000Z",
  "organisation_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "object": "test",
    "test": { "message": "This is a test webhook from your CRM." }
  }
}

Automation API calls

An automation's Call your API action posts to an endpoint you choose, through this same delivery pipeline — signed, retried, and recorded in the delivery log. It is not a subscription: nobody subscribes to automation.api_call, and it is delivered only to the URL configured on that step. See the Automations guide for how to set one up.

The envelope carries three things a subscription delivery can't: which automation fired, and the run's live context — the chat/contact/agent/ticket/call/survey values re-read at execution time, after any waits — alongside the trigger record itself in the usual data shape.

Headers. The standard delivery headers apply (X-Webhook-Id, X-Webhook-Timestamp, and X-Webhook-Signature when a signing secret is set — verified exactly as above), plus X-Webhook-Event: automation.api_call and any custom headers configured on the step. Three extra identity headers ride along:

Idempotency. Delivery is at-least-once (retries, and a step replay after an interrupted run). Deduplicate on run_id + step_id, which are stable across every attempt — not on id, which is per-delivery.

{
  "id": "b21c8e14-9f3a-4d77-a0c2-6e5b1f2d3c4a",
  "event": "automation.api_call",
  "api_version": "2026-05-01",
  "occurred_at": "2026-08-14T09:15:00.000Z",
  "organisation_id": "550e8400-e29b-41d4-a716-446655440000",
  "automation": {
    "rule_id": "9d3d5405-b33e-4cd5-9b1e-106a3cb8e116",
    "rule_name": "Unanswered handover watchdog",
    "run_id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "step_id": "8cfff0de-7cc4-4395-909a-5a7a312747d5",
    "trigger_event": "chat.assigned"
  },
  "data": {
    "object": "chat_assignment",
    "chat_assignment": {
      "chat_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "assignee_user_id": "8a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
      "previous_assignee_user_id": null
    }
  },
  "context": {
    "chat": {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "name": "Asha Patel",
      "primaryAssigneeUserId": "8a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
      "agentRepliedSinceTrigger": false,
      "resolved": false
    },
    "contact": { "e164": "+919812345678", "fullName": "Asha Patel" },
    "agent": { "userId": "8a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9", "fullName": "Priya Sharma" },
    "ticket": {}, "call": {}, "survey": {}
  }
}

Endpoint requirements. The URL must be http(s) and resolve to a public address — loopback, private, link-local and reserved ranges are refused at connection time, so an internal service cannot be reached even via DNS that resolves privately. Redirects are followed at most three times, each re-checked. Respond 2xx to acknowledge; anything else is retried with the standard backoff.

Managing endpoints via the API

Endpoints can be managed two ways. Both work on the same endpoints and count toward the same limit of 30.

With your API token (public API)

Authenticate with the JWT from POST /api/wp-crm/token (see Accounts & sign-in) as an Admin, Account Owner or service account (CRM_BOT). The organisationId in the path must be the organisation the token was issued for. This is the API an automation platform uses for instant triggers.

Each endpoint is returned as webhookId, url, events, description, isActive, headerNames, consecutiveFailures, disabledAt, createdByUserId, createdAt and updatedAt. Errors: 400 for an invalid URL, an unknown event or field, or an organisation that already has 30 endpoints (on samples: an unsupported event or a limit outside 1–10); 401 for a missing or expired token or another organisation's ID; 403 for any other role; 404 for a webhookId outside your organisation.

In a sample, occurred_at is when the record's event happened, and each envelope has its own random id. A few fields can differ from the delivery that record produced: contact.origin is always null, and a lead or message shows its current state (stage, delivery status) rather than its state when the event fired.

Zapier REST Hook triggers: register one endpoint per Zap. In the trigger's subscribe step, POST with url = bundle.targetUrl and the event you want, and keep the returned webhookId; in the unsubscribe step, DELETE …/{webhookId}; in Perform List, GET …/samples?event=… and read each sample the way Perform reads a delivery.

POST /api/wp-crm/webhooks/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <token>
Content-Type: application/json

{ "url": "https://hooks.zapier.com/hooks/standard/1234567/abcdef/", "events": ["lead.created"], "description": "Zapier — New lead" }

With a signed-in admin session (dashboard API)

Everything the Settings → Webhooks UI does is available under /wp-crm/webhooks for an Admin or Account Owner of the organisation, signed in to the dashboard. Every call names the organisation with the organisationId query parameter.

Create/update body fields (the public API's create takes the same fields as the dashboard's create; any other field is refused with 400)

Limits

• 30 endpoints per organisation, however they were created — Settings, the dashboard API or the public API. Each Zapier instant trigger uses one.
• 30 custom headers per endpoint (name ≤ 256 chars, value ≤ 2,048 chars, no line breaks).
• Endpoint URLs cannot target the Lodgestory API.
• Delivery log retention: 30 days (replay is available within that window).
• Response bodies are truncated to 1,000 bytes in the delivery log.

Related pages

• Webhooks settings guide — the product walkthrough: creating endpoints, delivery log, test and replay.
• Accounts & sign-in — authenticating against the Lodgestory public API for follow-up reads.
• AI assistants (MCP) — another way to act on Lodgestory data from your own tools.