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 tiers | All paid tiers. |
| Who can use it | Admins and Account Owners create and manage endpoints. |
| Channels covered | All — WhatsApp, Instagram, Messenger, Email, and Web Chat. |
| Events | 46 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 limits | Up to 30 endpoints per organisation. Up to 30 custom headers per endpoint. |
| Delivery | Signed (HMAC-SHA256), automatically retried, with a delivery log you can inspect and replay. |
| API | Yes — 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
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.createdandticket.assignedevents 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.

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.
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.

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.

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
- Something happens in Lodgestory — a message is sent or received, a ticket changes, a campaign finishes.
- Lodgestory checks which of your endpoints subscribe to that event.
- For each matching endpoint, Lodgestory builds a standard notification, signs it with that endpoint's secret, and delivers it to your URL.
- 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.
- 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
| Role | Can do |
|---|---|
| Account Owner / Admin | Create, edit, enable/disable, and delete endpoints; view and rotate secrets; view delivery logs; send test events; replay deliveries. |
| Service account | Through the API token only: create, list, test and delete endpoints. |
| Team member / Agent | No access to webhook settings. |
Connections
- Unified Inbox —
message.sentandmessage.receivedfire for every channel that lands in the inbox. - Tickets —
ticket.created,ticket.status_changed, andticket.assignedkeep an external helpdesk or on-call tool in sync. - Campaigns —
campaign.createdandcampaign.completedlet you track broadcast progress in your own reporting. - Contacts —
contact.creatednotifies you when a new contact is added from a conversation or the create-contact action. - WhatsApp Templates —
template.created,template.status_updated, andtemplate.quality_updatedtell you when a template is submitted, when Meta approves or rejects it, and when its quality rating moves. - WhatsApp Flows —
flow.response_receiveddelivers every completed flow's answers, correlated to the chat, journey, or campaign that sent it. - Workflow Lifecycle Stages —
chat.state_changedfires when a conversation moves between workflow stages. - Connections —
channel.connectedandchannel.disconnectednotify you when a channel is added or removed. - Instagram comment threads —
instagram.comment.receivedfires 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) andcall.quality_scored(a call's quality score and script check) mirror call activity into your own systems. - Bot Journeys —
goal.milestone_reachedfires 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.createdfires 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
| Event | Fires when |
|---|---|
message.sent | An outbound message is sent on any channel. |
message.received | An inbound message arrives on any channel. |
message.status_updated | A message's delivery status changes (sent / delivered / read / failed). |
template.created | A WhatsApp template is created and submitted. |
template.status_updated | A template is approved, rejected, or otherwise updated. |
template.quality_updated | Meta's quality rating for an approved template changes. |
ticket.created | A ticket is created. |
ticket.status_changed | A ticket is resolved or reopened. |
ticket.assigned | A ticket's assignee changes. |
contact.created | A contact is created. |
chat.resolved | A conversation is resolved (closed) or reopens — including auto-reopen on a new customer message. |
chat.assigned | A conversation's primary assignee is set or changed — bot handover, manual assignment, or an automation. |
chat.team_assigned | One or more teams are newly attached to a conversation (the routing moment, even when no individual owner is selected). |
chat.workflow_started | A workflow is attached to a conversation — the moment it enters the workflow. |
chat.state_changed | A conversation moves between workflow lifecycle stages. |
campaign.created | A campaign is created. |
campaign.completed | A campaign finishes sending — or fails because none of its audience could be messaged. Cancelled campaigns don't fire it. |
flow.response_received | A customer completes a WhatsApp Flow. |
channel.connected | A channel is connected. |
channel.disconnected | A channel is disconnected or removed. |
group.created | A 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.received | Someone 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.answered | A 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.completed | A call ends after being answered. |
call.missed | A call ends unanswered. |
call.recording_available | A call recording becomes available. |
call.transcript_available | A call transcript becomes available. |
call.summary_available | An 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_scored | An 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_updated | The AI summary of a customer — everything said across their calls and chats — is written or updated. Carries the summary, never message text. |
survey.response_submitted | A survey response is submitted, carrying the primary score and sentiment band. |
goal.milestone_reached | A live bot journey passes a Goal node, recording the milestone with its tracker values. Builder test-runs don't fire it. |
disposition.created | An 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.created | A lead is created — by hand, from an intake, an import, a Meta Instant Form, the API or an automation. |
lead.assigned | A lead's owner changes — a claim, a rule, a reassignment, a return to the pool, an SLA handover, a stale rescue. |
lead.stage_changed | A lead moves stage; status shows WON / LOST / JUNK when the stage closes it. |
lead.track_moved | A lead moves to another Track. |
lead.outcome_captured | An 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_breached | A new lead's first-response SLA expired before anyone dialled it. |
ai_request.created | The 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.answered | The 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.replied | Kaylee 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.removed | A 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
| Header | Purpose |
|---|---|
X-Webhook-Id | Unique delivery ID — use it for idempotency. |
X-Webhook-Event | The event type (matches event in the body). |
X-Webhook-Timestamp | When the delivery was signed (Unix seconds). |
X-Webhook-Signature | sha256=<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.sentandmessage.receivednow carrycrm_chat_id, the conversation ID the chat endpoints take, alongside the channel-levelchat_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 fullask_backsthread on the record. Ask back from your own systems with the AI requests API'sask-backendpoint (see the Kaylee console). - 2026-10-10 — Added
ai_request.createdandai_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), anddisposition.creatednow also fires for every outcome saved in the Agent Dialer (source_typeLEAD, withlead_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'schat_id. - 2026-08-17 — Added
group.created: WhatsApp group creation is asynchronous, and this event delivers the finished group'schat_id(correlated to an API create call byrequest_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) andchat.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.
Updated 18 days ago
