Webhooks

Lodgestory CRM › Settings → Webhooks

Added on request

Get real-time notifications in your own systems the moment something happens in Lodgestory — a message sent or received, a ticket created, a campaign finished, a channel connected.

TL;DR

  • What it is — you register an HTTPS endpoint, choose which events you care about, and Lodgestory sends a signed notification to that endpoint whenever one of those events happens, across every channel.
  • Who it's for — developers and technical teams who want to sync Lodgestory activity into a CRM, data warehouse, helpdesk, or any internal tool.
  • Top outcome — no polling. Your systems learn about messages, tickets, contacts, campaigns, and channel changes within seconds of them happening.

At a glance

Plan tiersAll paid tiers.
Who can use itAdmins and Account Owners create and manage endpoints.
Channels coveredAll — WhatsApp, Instagram, Messenger, Email, and Web Chat.
Events46 event types across messages, templates, tickets, contacts, chat lifecycle & workflow, dispositions, surveys, campaigns, channels, WhatsApp groups, Instagram comments, voice calls, goals, leads, the AI agent's requests to your team (Kaylee), and team membership.
Top limitsUp to 30 endpoints per organisation. Up to 30 custom headers per endpoint.
DeliverySigned (HMAC-SHA256), automatically retried, with a delivery log you can inspect and replay.
APIYes — create, list, test and delete endpoints with your API token (this is how Zapier's instant triggers connect), or manage everything through the dashboard API; receive events at your own endpoint.

How to find it

Sidebar: Settings → Webhooks.

Direct URL: https://lodgestory.com/crm/settings/webhooks

Webhooks page with Add Endpoint button and the empty state (no endpoints yet)

What is Webhooks?

The problem it solves

Most teams that want Lodgestory data in another system end up polling our API on a timer — asking "anything new?" over and over. That's slow, wasteful, and always a little behind. Webhooks flip it around: instead of you asking, Lodgestory tells you the instant something happens, so your CRM, data warehouse, or internal dashboard stays in sync in near real time.

What you get

  • Real-time event delivery — events reach your endpoint within seconds of happening.
  • Full coverage — one place to subscribe to messages, delivery statuses, templates, tickets, contacts, chat resolutions and assignments, chat-workflow transitions, survey responses, campaigns, Instagram comments, calls, goals, and channel connect/disconnect, across every channel.
  • The whole record, not just an ID — each notification carries the full object (the message, the ticket, the contact), so you usually don't need a follow-up API call.
  • Signed and verifiable — every delivery is signed with a secret only you and Lodgestory know, so you can confirm it really came from us.
  • Reliable delivery — failed deliveries are retried automatically with increasing delays; a delivery log lets you see exactly what happened and replay anything.

How it's different

You subscribe once and receive a single, consistent notification format for every event type — the same envelope whether it's a WhatsApp message, an email, a ticket assignment, or a campaign completion. The event type tells you what happened; the payload always carries the full object. That uniformity makes it fast to build one handler that routes everything.

Customer scenarios

  • A hotel group syncing to their PMS — every inbound guest message and ticket is pushed into their property-management system the moment it arrives, so front-desk staff see context without opening Lodgestory.
  • An agency with a data warehouse — campaign completions and message delivery statuses stream into their warehouse for reporting, with no nightly export job.
  • A team with a custom on-call tool — ticket.created and ticket.assigned events page the right person instantly.

How it fits with the rest of Lodgestory

Webhooks observe the rest of the platform — the Unified Inbox, Tickets, Campaigns, Contacts, WhatsApp Templates, Workflow Lifecycle Stages, and Connections — and forward those events to you.

Add webhook endpoint dialog filled with https://example.com/webhooks, a description and event checkboxes (Message received, Ticket created, Ticket assigned ticked)

Core concepts

  • Endpoint — an HTTPS URL you own that receives event notifications. You can have up to 30 per organisation, including the ones an automation platform such as Zapier creates through the API — those appear in this list too.
  • Event — something that happened in Lodgestory (for example, message.received). You choose which events each endpoint receives.
  • Signing secret — a unique secret generated for each endpoint. Lodgestory uses it to sign every delivery so you can verify authenticity. You can view or rotate it at any time.
  • Delivery — a single attempt (with retries) to send one event to one endpoint. Every delivery is recorded in the log.
  • Delivery log — the recent history of deliveries for an endpoint, including status, response code, and number of attempts. You can resend any past delivery.

Quick Start — receive your first event in 5 minutes

Step 1 — Open Webhooks

Go to Settings → Webhooks and click Add Endpoint.

Webhooks page header with the Add Endpoint button

Step 2 — Enter your endpoint URL

Paste the HTTPS URL that will receive events (for example, https://example.com/webhooks/lodgestory). Add an optional description so your team knows what it's for.

Step 3 — Choose your events

Tick the events you want this endpoint to receive, or use Select all. You can change this later.

Event checkboxes grouped by Chat Workflow, Dispositions, Leads, Channels, Instagram, Voice, Goals and Members

Step 4 — Save and copy your signing secret

When you create the endpoint, Lodgestory shows your signing secret once. Copy it and store it securely — you'll use it to verify deliveries. You can always copy or rotate it later from the endpoint's row.

Signing secret dialog after rotating a secret: the X-Webhook-Signature note, the new secret with a copy button, and Done

Step 5 — Send a test event

Click Send test on the endpoint to fire a sample notification at your URL, then check it arrived and that your signature check passes.

Step 6 — Verify and go live

Once your endpoint returns a success response (any 2xx) to the test, you're live. Real events will start flowing as they happen.

How it works

  1. Something happens in Lodgestory — a message is sent or received, a ticket changes, a campaign finishes.
  2. Lodgestory checks which of your endpoints subscribe to that event.
  3. For each matching endpoint, Lodgestory builds a standard notification, signs it with that endpoint's secret, and delivers it to your URL.
  4. If your endpoint doesn't respond with a success code, Lodgestory automatically retries with increasing delays — up to 6 attempts. Each delivery is recorded in the log.
  5. If an endpoint keeps failing over many events, Lodgestory pauses it automatically so it isn't hammered. You can re-enable it once it's fixed.

Behind the scenes Lodgestory does all of this asynchronously, so sending events never slows down your messaging or your team's inbox.

Features in depth

Choose exactly what you receive

Each endpoint subscribes to its own set of events. Point one endpoint at your CRM for messages and contacts, and another at your on-call tool for tickets only.

One consistent notification format

Every event uses the same envelope. The event field tells you what happened; data.object tells you the type of record; and data carries the full object. Update-type events (statuses, assignments, workflow transitions) also include a previous_attributes block showing what changed.

Signed deliveries

Every request includes a signature header computed from your endpoint's secret. Verifying it confirms the request genuinely came from Lodgestory and wasn't altered in transit. (See API → Verifying deliveries.)

Automatic retries and auto-pause

Temporary outages on your side are handled for you: failed deliveries are retried automatically with growing delays. If an endpoint fails consistently across many events, it's paused so it stops receiving traffic until you re-enable it.

Delivery log, test, and replay

Open any endpoint's delivery log to see recent attempts with their status, response code, and attempt count. Send test fires a sample event on demand. Redeliver re-sends any past delivery — useful after you fix a bug on your side.

Rotate the secret

Rotate an endpoint's signing secret at any time (for example, if it may have leaked). Update your verification code with the new secret to continue accepting deliveries.

Roles & permissions

RoleCan do
Account Owner / AdminCreate, edit, enable/disable, and delete endpoints; view and rotate secrets; view delivery logs; send test events; replay deliveries.
Service accountThrough the API token only: create, list, test and delete endpoints.
Team member / AgentNo access to webhook settings.

Connections

  • Unified Inbox — message.sent and message.received fire for every channel that lands in the inbox.
  • Tickets — ticket.created, ticket.status_changed, and ticket.assigned keep an external helpdesk or on-call tool in sync.
  • Campaigns — campaign.created and campaign.completed let you track broadcast progress in your own reporting.
  • Contacts — contact.created notifies you when a new contact is added from a conversation or the create-contact action.
  • WhatsApp Templates — template.created, template.status_updated, and template.quality_updated tell you when a template is submitted, when Meta approves or rejects it, and when its quality rating moves.
  • WhatsApp Flows — flow.response_received delivers every completed flow's answers, correlated to the chat, journey, or campaign that sent it.
  • Workflow Lifecycle Stages — chat.state_changed fires when a conversation moves between workflow stages.
  • Connections — channel.connected and channel.disconnected notify you when a channel is added or removed.
  • Instagram comment threads — instagram.comment.received fires for every comment on your Instagram posts, reels and ads once Comments in inbox is on for the account — build keyword alerts, moderation queues, or your own comment-to-DM flows on it.
  • Calls — call.answered (the moment a call is picked up — for screen-pops in your own CRM), call.completed, call.missed, call.recording_available, call.transcript_available, call.summary_available (the AI summary of a call) and call.quality_scored (a call's quality score and script check) mirror call activity into your own systems.
  • Bot Journeys — goal.milestone_reached fires when a live journey passes a Goal node, with the captured tracker values — pipe conversions and outcomes straight into your analytics or CRM.
  • Meta Ads Lead Signals — disposition.created fires on every captured outcome; the same event drives the disposition → Meta signal rules, so what your endpoint sees is exactly what Meta is told.

Limits a user will run into

  • 30 endpoints per organisation, counting the ones created through the API — each Zapier instant trigger uses one. Delete one before adding another if you hit the limit.
  • Custom headers: up to 30 per endpoint; names and values must be plain text with no line breaks.
  • Endpoint URL: must be a reachable HTTPS URL; it can't point at the Lodgestory API itself.
  • Delivery history is retained for 30 days.
  • Bulk operations (such as a large contact import) don't fire per-record events, to avoid flooding your endpoint.

Errors & FAQ

My endpoint isn't receiving events. Check that the endpoint is enabled, that it's subscribed to the event you expect, and that your URL returns a 2xx response. Use Send test and the delivery log to diagnose.

My endpoint was disabled automatically. That happens after many consecutive failed deliveries. Fix your endpoint, then re-enable it from its row — re-enabling clears the failure count.

Signature verification fails. Make sure you're computing the signature over the exact raw request body (not a re-serialized version) together with the timestamp header, using the current secret. If you recently rotated the secret, update your verification code.

I received the same event twice. Treat deliveries as at-least-once. Use the delivery ID (the id field, also in the X-Webhook-Id header) to make your handler idempotent.

Do campaign sends fire a message.sent per recipient? Yes — each outbound message is a real send. Subscribe to message.sent only if you want that volume.

API

Webhooks are a developer feature. There are two surfaces: the admin API to manage endpoints, and the delivery contract for the events you receive.

Full reference: this section is a summary. The complete developer contract — every event's exact payload fields with examples, signature verification in Node.js and Python, retry timing, and the endpoint-management API — lives in the Webhooks API reference.

Events you can subscribe to

EventFires when
message.sentAn outbound message is sent on any channel.
message.receivedAn inbound message arrives on any channel.
message.status_updatedA message's delivery status changes (sent / delivered / read / failed).
template.createdA WhatsApp template is created and submitted.
template.status_updatedA template is approved, rejected, or otherwise updated.
template.quality_updatedMeta's quality rating for an approved template changes.
ticket.createdA ticket is created.
ticket.status_changedA ticket is resolved or reopened.
ticket.assignedA ticket's assignee changes.
contact.createdA contact is created.
chat.resolvedA conversation is resolved (closed) or reopens — including auto-reopen on a new customer message.
chat.assignedA conversation's primary assignee is set or changed — bot handover, manual assignment, or an automation.
chat.team_assignedOne or more teams are newly attached to a conversation (the routing moment, even when no individual owner is selected).
chat.workflow_startedA workflow is attached to a conversation — the moment it enters the workflow.
chat.state_changedA conversation moves between workflow lifecycle stages.
campaign.createdA campaign is created.
campaign.completedA campaign finishes sending — or fails because none of its audience could be messaged. Cancelled campaigns don't fire it.
flow.response_receivedA customer completes a WhatsApp Flow.
channel.connectedA channel is connected.
channel.disconnectedA channel is disconnected or removed.
group.createdA WhatsApp group appears on one of your WhatsApp Official channels — including groups created via the API (the payload's request_id correlates to your create call, and chat_id is ready to message and assign).
instagram.comment.receivedSomeone comments on one of your Instagram posts, reels or ads (Instagram accounts with Comments in inbox on). Carries the comment, the commenter, and the post; chat_id is the post's comment thread. Your own comments never fire it.
call.answeredA Lodgestory Voice call is picked up — an agent answers an inbound call, or the customer answers an agent's outbound or click-to-call. Sent again for the new agent after a transfer.
call.completedA call ends after being answered.
call.missedA call ends unanswered.
call.recording_availableA call recording becomes available.
call.transcript_availableA call transcript becomes available.
call.summary_availableAn AI summary of a call is written or rewritten (someone clicked Summarise call, or automatic summaries are on). Carries the summary, never the transcript.
call.quality_scoredAn admin scored a call against a scorecard and/or its call script, or scored it again. Carries the score, each item's result with short quotes, the script steps followed or missed, and coaching tips — never the transcript.
customer.summary_updatedThe AI summary of a customer — everything said across their calls and chats — is written or updated. Carries the summary, never message text.
survey.response_submittedA survey response is submitted, carrying the primary score and sentiment band.
goal.milestone_reachedA live bot journey passes a Goal node, recording the milestone with its tracker values. Builder test-runs don't fire it.
disposition.createdAn advisor captures a disposition (outcome form) on a chat, call, booking or lead. Carries the template, the answers keyed by field id, and the chat / call / booking / lead it belongs to.
lead.createdA lead is created — by hand, from an intake, an import, a Meta Instant Form, the API or an automation.
lead.assignedA lead's owner changes — a claim, a rule, a reassignment, a return to the pool, an SLA handover, a stale rescue.
lead.stage_changedA lead moves stage; status shows WON / LOST / JUNK when the stage closes it.
lead.track_movedA lead moves to another Track.
lead.outcome_capturedAn outcome is recorded for one attempt on a lead — once per dial, with the lead attached. A call placed to the lead outside the dialer emits this when an agent saves its outcome.
lead.sla_breachedA new lead's first-response SLA expired before anyone dialled it.
ai_request.createdThe Bot Journey AI agent asked your team a question, offered it a choice, or held a change for a teammate's approval. Fires the moment the request is raised; test runs never fire it. Answer it from your own systems with the AI requests API.
ai_request.answeredThe request was settled — answered, approved or rejected by a person (and from where: console, conversation, team chat, mobile, phone, API), or closed by Lodgestory because nobody answered in time, the agent withdrew it, a teammate replied in the conversation, or took it over.
ai_request.repliedKaylee replied to a teammate's ask-back on an open request — answered them, or asked the customer about it first. The request is still open; the full thread rides along on the record.
member.removedA member is removed from the organisation. The payload includes their removed roles and how many open chats and tickets became unassigned.

The notification format

Every delivery is an HTTP POST with this JSON body:

{
  "id": "f1c2…",
  "event": "message.received",
  "api_version": "2026-05-01",
  "occurred_at": "2026-05-25T10:14:02.000Z",
  "organisation_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "object": "message",
    "message": {
      "id": "wamid.HBgL…",
      "chat_id": "[email protected]",
      "crm_chat_id": "d290f1ee-…",
      "channel_id": "…",
      "channel_type": "whatsapp",
      "direction": "inbound",
      "type": "text",
      "text": "Is breakfast included?",
      "media_uri": null,
      "status": "DELIVERED",
      "from_name": "John Doe",
      "from_number": "+919999999999",
      "timestamp": "2026-05-25T10:14:02.000Z"
    }
  }
}

Update-type events also include previous_attributes. For example, ticket.status_changed:

{
  "event": "ticket.status_changed",
  "api_version": "2026-05-01",
  "occurred_at": "2026-05-25T11:02:00.000Z",
  "organisation_id": "550e8400-…",
  "data": {
    "object": "ticket",
    "ticket": {
      "id": "…",
      "ticket_number": 42,
      "chat_id": "…",
      "call_log_id": null,
      "status": "resolved",
      "priority": "HIGH_PRIORITY",
      "assigned_to_user_id": "…",
      "created_at": "2026-05-24T09:00:00.000Z",
      "updated_at": "2026-05-25T11:02:00.000Z"
    },
    "previous_attributes": { "status": "open" }
  }
}

data.object is one of message, message_status, template, ticket, contact, chat_state, campaign, channel, instagram_comment, call, goal_milestone, or member, and the object's full payload is under the matching key. Every object's field-by-field shape is documented in the Webhooks API reference.

A goal.milestone_reached delivery, for example, carries the goal, milestone, chat, and captured tracker values:

{
  "event": "goal.milestone_reached",
  "data": {
    "object": "goal_milestone",
    "goal_milestone": {
      "id": "…",
      "goal_id": "…",
      "goal_name": "Bookings",
      "milestone_id": "…",
      "milestone_name": "Booking confirmed",
      "journey_id": "…",
      "chat_id": "…",
      "channel_chat_id": "[email protected]",
      "chat_name": "John Doe",
      "channel_id": "…",
      "tracker_values": { "Order_ID": "ORD-1042", "Room_Type": "Deluxe" },
      "recorded_at": "2026-07-20T09:15:00.000Z"
    }
  }
}

Headers on every delivery

HeaderPurpose
X-Webhook-IdUnique delivery ID — use it for idempotency.
X-Webhook-EventThe event type (matches event in the body).
X-Webhook-TimestampWhen the delivery was signed (Unix seconds).
X-Webhook-Signaturesha256=<hmac> — see below.

Verifying deliveries

The signature is an HMAC-SHA256, using your endpoint's signing secret, computed over the timestamp and the raw request body joined by a dot: {timestamp}.{body}. To verify, recompute it and compare:

import crypto from 'crypto';

function isValid(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 you received
      .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Always use the raw, unparsed body — re-serializing the JSON will change the bytes and break the check.

Responding

Return any 2xx status to acknowledge a delivery. Any other status (or a timeout — each attempt waits up to 10 seconds) is treated as a failure and retried automatically, up to 6 attempts with increasing delays. Endpoints that fail consistently across many events are paused automatically.

Managing endpoints

With your API token, Admins, Account Owners and service accounts can create, list, test and delete endpoints under /api/wp-crm/webhooks/{organisationId}. This is what an automation platform calls when a workflow with an instant trigger is switched on or off. The signing secret is returned once, when the endpoint is created.

Signed in to the dashboard, Admins can also update, enable/disable, rotate secrets, list deliveries and replay a delivery through the dashboard API under /wp-crm/webhooks. The same actions are available in the UI. Both are described in the Webhooks API reference.

Changelog

  • 2026-11-05 — message.sent and message.received now carry crm_chat_id, the conversation ID the chat endpoints take, alongside the channel-level chat_id.
  • 2026-10-25 — Create, list, test and delete endpoints with your API token (/api/wp-crm/webhooks/{organisationId}), as Admin, Account Owner or service account — the calls Zapier's instant triggers make when a Zap is switched on or off. The limit rises from 3 to 30 endpoints per organisation.
  • 2026-10-15 — Added ai_request.replied: Kaylee's reply to a teammate's ask-back on an open request — or her question to the customer about it — with the full ask_backs thread on the record. Ask back from your own systems with the AI requests API's ask-back endpoint (see the Kaylee console).
  • 2026-10-10 — Added ai_request.created and ai_request.answered: the Bot Journey AI agent's questions to your team and the changes it holds for approval, and how each was settled — answerable from your own systems through the AI requests API (see the Kaylee console).
  • 2026-09-18 — Added the lead events (lead.created, lead.assigned, lead.stage_changed, lead.track_moved, lead.outcome_captured, lead.sla_breached), and disposition.created now also fires for every outcome saved in the Agent Dialer (source_type LEAD, with lead_id).
  • 2026-09-04 — Added disposition.created: every captured disposition (chat, call or booking outcome) is delivered with its template, answers and source ids.
  • 2026-08-28 — Added instagram.comment.received: comments on your Instagram posts, reels and ads (once Comments in inbox is on for the account) are delivered with the comment, the commenter, the post, and the comment thread's chat_id.
  • 2026-08-17 — Added group.created: WhatsApp group creation is asynchronous, and this event delivers the finished group's chat_id (correlated to an API create call by request_id) — the push-based alternative to polling the groups creation-status endpoint.
  • 2026-08-14 — Added chat.assigned (a conversation's primary assignee is set or changed) and chat.team_assigned (teams newly attached to a conversation) — the handover and routing moments, built for "assigned but never answered" watchdogs and external routing mirrors.
  • 2026-07-20 — Added goal.milestone_reached: bot-journey Goal milestones (with their captured tracker values) can now be delivered to your endpoints. Fires for live conversations only.
  • 2026-01-12 — Webhooks launched: 14 event types across all channels, signed delivery with automatic retries, a delivery log with test and replay, and per-endpoint custom headers.

Related modules & next steps

  • Webhooks API reference — the full developer contract: every event's payload fields, signature verification code, and the management API.
  • Connections — connect the channels whose events you'll receive.
  • Tickets and Campaigns — common event sources.
  • WhatsApp Templates — track template approval via template.status_updated.
  • Bot Journeys — define the Goals whose milestones arrive via goal.milestone_reached.

Did this page help you?