Webhooks
Get a signed message in your own system the moment a post goes live, a customer writes in or a lead arrives.
For developers
On this page
A webhook is a web address in your own system that Luminobot calls whenever something happens. Instead of asking "anything new?" every few minutes, your system is told straight away. Use it to update a CRM when a lead comes in, post to a chat channel when a post fails, or log every new message.
Each event is a JSON POST to an https:// address you choose, signed so you can check it really came from Luminobot.
Add a webhook
You need to be an organization owner or admin.
- Open Settings → API & Webhooks and click the Webhooks tab.
- Under Add a webhook, fill in:
- Name: for example "CRM" or "Slack alerts".
- Endpoint URL: the
https://address that will receive the events. It must be a public address; private and local addresses are refused, and redirects are not followed. - Workspaces: All workspaces, or just one.
- Events: tick the events you want, or use Recommended, All or None.
- Click Add webhook.
- Copy the signing secret (it starts with
whsec_). It is shown only once. You need it to check signatures. - Click Send test on the new webhook. Your endpoint should receive a
testevent and answer with a2xxstatus. The status pill then shows Working.
Each webhook row also has Deliveries (the log of what was sent), Edit, Pause / Turn on, Rotate secret and Remove. An organization can have up to 25 webhooks.
What you receive
POST /hooks/events HTTP/1.1
Content-Type: application/json
User-Agent: Webhooks/1.0
X-Webhook-Id: 2f0c1d5e-6a63-4c55-9a3e-0b9c7f1e8d21
X-Webhook-Event: post.published
X-Webhook-Timestamp: 1792318323
X-Webhook-Attempt: 1
X-Webhook-Signature: t=1792318323,v1=6c1f…e09b
{"id": "evt_…", "type": "post.published", "version": 1, "created_at": "…",
"organization": {"id": "…"}, "workspace": {"id": "…", "name": "Acme Coffee"},
"data": {…}, "test": false}
| Part | Meaning |
|---|---|
id |
The event. Every webhook that gets this event sees the same id. |
type |
The event name, such as post.published. |
version |
The payload version, now 1. New fields may appear at any time; removing or changing a field means a new version. |
created_at |
When it happened (UTC). Events can arrive out of order, so use this to sort them. |
data |
The details. Each event's shape is shown in the Events section at the end of this page. |
test |
true only for test events. |
X-Webhook-Id |
The delivery. It stays the same on every retry. Store it and ignore repeats. |
X-Webhook-Attempt |
1 the first time, 2 and up for retries. |
X-Webhook-Signature |
The signature to check (below). |
Answer quickly. Reply with any 2xx status within 10 seconds, then do the real work afterwards (put it in a queue). Only the first 2 KB of your answer is read.
Check the signature
Anyone could send a request to your address, so always check the signature before you trust an event. v1 is an HMAC-SHA256 of <t>.<raw body>, using your signing secret as the key.
- Use the raw request body exactly as received, before any JSON parsing.
- Compare in constant time.
- Accept any of the
v1values (there are two for a while after you rotate the secret). - Reject timestamps older than 5 minutes, so an old request can't be replayed.
Python
import hashlib
import hmac
import time
def verify_webhook(secret: str, signature_header: str, raw_body: bytes, tolerance: int = 300) -> bool:
parts = [p.strip().split("=", 1) for p in signature_header.split(",") if "=" in p]
timestamps = [v for k, v in parts if k == "t"]
if not timestamps or abs(time.time() - int(timestamps[0])) > tolerance:
return False
signed = timestamps[0].encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return any(k == "v1" and hmac.compare_digest(v, expected) for k, v in parts)
# Flask example
# @app.post("/hooks/events")
# def hook():
# if not verify_webhook(SECRET, request.headers["X-Webhook-Signature"], request.get_data()):
# abort(400)
# if already_seen(request.headers["X-Webhook-Id"]):
# return "", 200
# queue_event(request.get_json())
# return "", 200
Node.js
const crypto = require("crypto");
function verifyWebhook(secret, signatureHeader, rawBody, toleranceSeconds = 300) {
const parts = signatureHeader.split(",").map((p) => p.trim().split("=", 2));
const t = (parts.find(([k]) => k === "t") || [])[1];
if (!t || Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false;
const expected = crypto.createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest("hex");
return parts.some(([k, v]) =>
k === "v1" && v.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(v, "hex"), Buffer.from(expected, "hex")));
}
// Express: keep the raw body for the signature check.
// app.post("/hooks/events", express.raw({ type: "application/json" }), (req, res) => {
// if (!verifyWebhook(SECRET, req.get("X-Webhook-Signature"), req.body)) return res.sendStatus(400);
// const event = JSON.parse(req.body);
// res.sendStatus(200);
// queueEvent(req.get("X-Webhook-Id"), event);
// });
Rotating the secret
Click Rotate secret to get a new one (shown once). Tick "Keep signing with the old secret too for 24 hours" to switch without missing events: during that time every request carries two v1= signatures, one per secret. Update your endpoint, then let the old secret expire.
When your endpoint fails
- Any answer other than
2xx, a timeout or a connection error is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours — six tries in all, always with the sameX-Webhook-Id. - While an endpoint keeps failing, new events for it wait in line and are tried one at a time, so it isn't flooded when it comes back.
- A webhook that failed 20 times in a row and kept failing for 24 hours is turned off. Its waiting events are dropped and organization owners and admins get a notification and an email. Fix the endpoint, click Send test, then Turn on.
- Send test and manual Redeliver never count toward turning a webhook off.
- Pause stops sending and drops waiting events.
- The Deliveries log keeps 30 days of history: status, tries, the HTTP code, any error and the payload. Redeliver sends a logged delivery again with the same id.
Manage webhooks with the API
Your software can manage its own webhooks through the Agent API at /api/v1/webhooks/ (or AI assistants with the MCP tools list_webhooks, create_webhook, update_webhook, delete_webhook, list_webhook_deliveries and redeliver_webhook).
curl -s -X POST https://app.luminobot.com/api/v1/webhooks/ \
-H "Authorization: Bearer $BRAND_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "CRM", "url": "https://hooks.example.com/events", "event_types": ["lead.submitted", "post.failed"]}'
The answer (201) includes the secret — once. A few rules keep this safe:
- The key needs the
manage_workspace_settingspermission, and the person who created the key must still be an organization owner or admin. - A key only sees and manages the webhooks it created, in its own workspace. Webhooks made on the settings page or by other keys are invisible to it.
- A key-created webhook only gets events about the key's accounts and only the kinds of events the key may read: inbox events need
use_inbox, contact and lead eventsuse_contacts, workflow eventsuse_workflows. - Revoking the key turns its webhooks off.
GET /api/v1/webhooks/event-types/ lists every event with an example. The full list of webhook endpoints is in the API reference.
Security
- Endpoint addresses and secrets are stored encrypted. After saving, only the host name is shown.
- Every request goes to the address that was just checked, so a DNS trick can't send events somewhere private.
- Payloads never contain passwords, access tokens, API keys, AI tool arguments or internal notes. Message text, contact details and lead answers only appear in the events about them.
- Events are only sent after a change is saved. A change that is rolled back sends nothing.
Events
There are 15 events. Every delivery has the same outer shape; only data changes. Values like … are shortened in these examples.
Posts
post.created — Post created
A post (draft or scheduled) was created in the composer, by the Agent API or by a workflow.
{
"id": "evt_5f2c0f9b6c3e4f0e8f1a2b3c4d5e6f70",
"type": "post.created",
"version": 1,
"created_at": "2026-10-18T10:12:03.402115+00:00",
"organization": {
"id": "…"
},
"workspace": {
"id": "…",
"name": "Acme Coffee"
},
"data": {
"post": {
"id": "3a41…",
"title": "",
"caption": "Our autumn menu is here!",
"status": "scheduled",
"scheduled_at": "2026-10-20T09:00:00+00:00",
"author": {
"id": "c0de…",
"name": "Olivia Owner"
},
"url": "https://app.example.com/workspace/…/posts/…"
},
"targets": [
{
"id": "77aa…",
"social_account": {
"id": "6f1c…",
"platform": "instagram",
"name": "Acme Coffee"
},
"status": "scheduled",
"scheduled_at": "2026-10-20T09:00:00+00:00",
"published_at": null,
"platform_post_id": "",
"error": ""
}
]
},
"test": false
}
post.scheduled — Post scheduled
One or more of a post's networks were scheduled (targets lists which).
Recommended: it is ticked by default when you add a webhook.
{
"id": "evt_5f2c0f9b6c3e4f0e8f1a2b3c4d5e6f70",
"type": "post.scheduled",
"version": 1,
"created_at": "2026-10-18T10:12:03.402115+00:00",
"organization": {
"id": "…"
},
"workspace": {
"id": "…",
"name": "Acme Coffee"
},
"data": {
"post": {
"id": "3a41…",
"title": "",
"caption": "Our autumn menu is here!",
"status": "scheduled",
"scheduled_at": "2026-10-20T09:00:00+00:00",
"author": {
"id": "c0de…",
"name": "Olivia Owner"
},
"url": "https://app.example.com/workspace/…/posts/…"
},
"targets": [
{
"id": "77aa…",
"social_account": {
"id": "6f1c…",
"platform": "instagram",
"name": "Acme Coffee"
},
"status": "scheduled",
"scheduled_at": "2026-10-20T09:00:00+00:00",
"published_at": null,
"platform_post_id": "",
"error": ""
}
]
},
"test": false
}
post.published — Post published
A post went live on a network (one event per publish run).
Recommended: it is ticked by default when you add a webhook.
{
"id": "evt_5f2c0f9b6c3e4f0e8f1a2b3c4d5e6f70",
"type": "post.published",
"version": 1,
"created_at": "2026-10-18T10:12:03.402115+00:00",
"organization": {
"id": "…"
},
"workspace": {
"id": "…",
"name": "Acme Coffee"
},
"data": {
"post": {
"id": "3a41…",
"title": "",
"caption": "Our autumn menu is here!",
"status": "published",
"scheduled_at": "2026-10-20T09:00:00+00:00",
"author": {
"id": "c0de…",
"name": "Olivia Owner"
},
"url": "https://app.example.com/workspace/…/posts/…"
},
"targets": [
{
"id": "77aa…",
"social_account": {
"id": "6f1c…",
"platform": "instagram",
"name": "Acme Coffee"
},
"status": "published",
"scheduled_at": "2026-10-20T09:00:00+00:00",
"published_at": "…",
"platform_post_id": "17895…",
"error": ""
}
]
},
"test": false
}
post.failed — Post failed
Publishing to a network failed after all retries (error says why).
Recommended: it is ticked by default when you add a webhook.
{
"id": "evt_5f2c0f9b6c3e4f0e8f1a2b3c4d5e6f70",
"type": "post.failed",
"version": 1,
"created_at": "2026-10-18T10:12:03.402115+00:00",
"organization": {
"id": "…"
},
"workspace": {
"id": "…",
"name": "Acme Coffee"
},
"data": {
"post": {
"id": "3a41…",
"title": "",
"caption": "Our autumn menu is here!",
"status": "failed",
"scheduled_at": "2026-10-20T09:00:00+00:00",
"author": {
"id": "c0de…",
"name": "Olivia Owner"
},
"url": "https://app.example.com/workspace/…/posts/…"
},
"targets": [
{
"id": "77aa…",
"social_account": {
"id": "6f1c…",
"platform": "instagram",
"name": "Acme Coffee"
},
"status": "failed",
"scheduled_at": "2026-10-20T09:00:00+00:00",
"published_at": null,
"platform_post_id": "",
"error": "The account needs reconnecting."
}
]
},
"test": false
}
post.approved — Post approved
A post cleared approval (every step in multi-step approval).
Recommended: it is ticked by default when you add a webhook.
{
"id": "evt_5f2c0f9b6c3e4f0e8f1a2b3c4d5e6f70",
"type": "post.approved",
"version": 1,
"created_at": "2026-10-18T10:12:03.402115+00:00",
"organization": {
"id": "…"
},
"workspace": {
"id": "…",
"name": "Acme Coffee"
},
"data": {
"post": {
"id": "3a41…",
"title": "",
"caption": "Our autumn menu is here!",
"status": "approved",
"scheduled_at": "2026-10-20T09:00:00+00:00",
"author": {
"id": "c0de…",
"name": "Olivia Owner"
},
"url": "https://app.example.com/workspace/…/posts/…"
},
"targets": [
{
"id": "77aa…",
"social_account": {
"id": "6f1c…",
"platform": "instagram",
"name": "Acme Coffee"
},
"status": "approved",
"scheduled_at": "2026-10-20T09:00:00+00:00",
"published_at": null,
"platform_post_id": "",
"error": ""
}
],
"decision": {
"by": {
"id": "c0de…",
"name": "Rami Reviewer"
},
"comment": "Looks great",
"via": ""
}
},
"test": false
}
post.rejected — Post rejected
A reviewer rejected a post.
Recommended: it is ticked by default when you add a webhook.
{
"id": "evt_5f2c0f9b6c3e4f0e8f1a2b3c4d5e6f70",
"type": "post.rejected",
"version": 1,
"created_at": "2026-10-18T10:12:03.402115+00:00",
"organization": {
"id": "…"
},
"workspace": {
"id": "…",
"name": "Acme Coffee"
},
"data": {
"post": {
"id": "3a41…",
"title": "",
"caption": "Our autumn menu is here!",
"status": "rejected",
"scheduled_at": "2026-10-20T09:00:00+00:00",
"author": {
"id": "c0de…",
"name": "Olivia Owner"
},
"url": "https://app.example.com/workspace/…/posts/…"
},
"targets": [
{
"id": "77aa…",
"social_account": {
"id": "6f1c…",
"platform": "instagram",
"name": "Acme Coffee"
},
"status": "rejected",
"scheduled_at": "2026-10-20T09:00:00+00:00",
"published_at": null,
"platform_post_id": "",
"error": ""
}
],
"decision": {
"by": {
"id": "c0de…",
"name": "Rami Reviewer"
},
"comment": "Off brand",
"via": ""
}
},
"test": false
}
Inbox
message.received — Message received
A customer's DM, comment, mention or review arrived (live messages only — never imported history, our own replies or CSAT answers).
A webhook created with an API key only gets this event when the key may use the inbox (use_inbox).
{
"id": "evt_5f2c0f9b6c3e4f0e8f1a2b3c4d5e6f70",
"type": "message.received",
"version": 1,
"created_at": "2026-10-18T10:12:03.402115+00:00",
"organization": {
"id": "…"
},
"workspace": {
"id": "…",
"name": "Acme Coffee"
},
"data": {
"message": {
"id": "0b6c…",
"type": "dm",
"platform": "instagram",
"social_account": {
"id": "6f1c…",
"platform": "instagram",
"name": "Acme Coffee"
},
"sender": {
"name": "Sam Customer",
"handle": "sam.c"
},
"body": "Hi! Are you open on Sunday?",
"media_type": "",
"received_at": "2026-10-18T10:12:00+00:00",
"contact_id": "9d2e…",
"related_post_id": null,
"url": "https://app.example.com/workspace/…/inbox/0b6c…/"
}
},
"test": false
}
conversation.assigned — Conversation assigned
A conversation was assigned to a teammate (by a person, a rule, a team or a workflow).
Recommended: it is ticked by default when you add a webhook. A webhook created with an API key only gets this event when the key may use the inbox (use_inbox).
{
"id": "evt_5f2c0f9b6c3e4f0e8f1a2b3c4d5e6f70",
"type": "conversation.assigned",
"version": 1,
"created_at": "2026-10-18T10:12:03.402115+00:00",
"organization": {
"id": "…"
},
"workspace": {
"id": "…",
"name": "Acme Coffee"
},
"data": {
"conversation": {
"message_id": "0b6c…",
"type": "dm",
"platform": "instagram",
"social_account": {
"id": "6f1c…",
"platform": "instagram",
"name": "Acme Coffee"
},
"status": "open",
"priority": "",
"contact_id": "9d2e…",
"assignee": {
"id": "a11c…",
"name": "Ana Agent",
"email": "ana@…"
},
"url": "https://app.example.com/workspace/…/inbox/0b6c…/"
},
"assignee": {
"id": "a11c…",
"name": "Ana Agent",
"email": "ana@…"
}
},
"test": false
}
conversation.resolved — Conversation resolved
A conversation was marked resolved.
A webhook created with an API key only gets this event when the key may use the inbox (use_inbox).
{
"id": "evt_5f2c0f9b6c3e4f0e8f1a2b3c4d5e6f70",
"type": "conversation.resolved",
"version": 1,
"created_at": "2026-10-18T10:12:03.402115+00:00",
"organization": {
"id": "…"
},
"workspace": {
"id": "…",
"name": "Acme Coffee"
},
"data": {
"conversation": {
"message_id": "0b6c…",
"type": "dm",
"platform": "instagram",
"social_account": {
"id": "6f1c…",
"platform": "instagram",
"name": "Acme Coffee"
},
"status": "resolved",
"priority": "",
"contact_id": "9d2e…",
"assignee": null,
"url": "https://app.example.com/workspace/…/inbox/0b6c…/"
}
},
"test": false
}
csat.received — CSAT rating received
A customer answered the satisfaction survey (1–5).
A webhook created with an API key only gets this event when the key may use the inbox (use_inbox).
{
"id": "evt_5f2c0f9b6c3e4f0e8f1a2b3c4d5e6f70",
"type": "csat.received",
"version": 1,
"created_at": "2026-10-18T10:12:03.402115+00:00",
"organization": {
"id": "…"
},
"workspace": {
"id": "…",
"name": "Acme Coffee"
},
"data": {
"csat": {
"rating": 5,
"comment": "Super quick, thanks!",
"satisfied": true,
"answered_at": "…",
"survey_sent_at": "…"
},
"conversation": {
"message_id": "0b6c…",
"type": "dm",
"platform": "instagram",
"social_account": {
"id": "6f1c…",
"platform": "instagram",
"name": "Acme Coffee"
},
"status": "resolved",
"priority": "",
"contact_id": "9d2e…",
"assignee": null,
"url": "https://app.example.com/workspace/…/inbox/0b6c…/"
}
},
"test": false
}
ai_action.awaiting_approval — AI action awaiting approval
An AI Employee wants to run an action that needs a teammate's approval (decide with POST /api/v1/ai/actions/{id}/approve/ or /reject/).
Recommended: it is ticked by default when you add a webhook. A webhook created with an API key only gets this event when the key may use the inbox (use_inbox).
{
"id": "evt_5f2c0f9b6c3e4f0e8f1a2b3c4d5e6f70",
"type": "ai_action.awaiting_approval",
"version": 1,
"created_at": "2026-10-18T10:12:03.402115+00:00",
"organization": {
"id": "…"
},
"workspace": {
"id": "…",
"name": "Acme Coffee"
},
"data": {
"action": {
"id": "e5f0…",
"ai_employee": {
"id": "41b2…",
"name": "Ava"
},
"message_id": "0b6c…",
"calls": [
{
"tool": "assign_to",
"summary": "Assign the conversation to Ana Agent"
}
],
"digest": "9f86d0…",
"created_at": "…",
"url": "https://app.example.com/workspace/…/inbox/0b6c…/"
},
"conversation": {
"message_id": "0b6c…",
"type": "dm",
"platform": "instagram",
"social_account": {
"id": "6f1c…",
"platform": "instagram",
"name": "Acme Coffee"
},
"status": "open",
"priority": "",
"contact_id": "9d2e…",
"assignee": null,
"url": "https://app.example.com/workspace/…/inbox/0b6c…/"
}
},
"test": false
}
Contacts
contact.created — Contact created
A contact was added: a new person wrote in, a lead form, a teammate or the API (not bulk imports).
A webhook created with an API key only gets this event when the key may use contacts (use_contacts). Not tied to one connected account, so a key's account list doesn't filter it.
{
"id": "evt_5f2c0f9b6c3e4f0e8f1a2b3c4d5e6f70",
"type": "contact.created",
"version": 1,
"created_at": "2026-10-18T10:12:03.402115+00:00",
"organization": {
"id": "…"
},
"workspace": {
"id": "…",
"name": "Acme Coffee"
},
"data": {
"contact": {
"id": "9d2e…",
"display_name": "Sam Customer",
"email": "sam@example.com",
"phone": "+15551234567",
"tags": [
"vip"
],
"lifecycle_stage": "lead",
"custom_fields": {
"plan": "pro"
},
"consent_status": "opted_in",
"created_at": "…",
"updated_at": "…"
}
},
"test": false
}
contact.updated — Contact updated
A contact's name, email, phone, tags, lifecycle stage, custom fields or consent changed (changed lists which).
A webhook created with an API key only gets this event when the key may use contacts (use_contacts). Not tied to one connected account, so a key's account list doesn't filter it.
{
"id": "evt_5f2c0f9b6c3e4f0e8f1a2b3c4d5e6f70",
"type": "contact.updated",
"version": 1,
"created_at": "2026-10-18T10:12:03.402115+00:00",
"organization": {
"id": "…"
},
"workspace": {
"id": "…",
"name": "Acme Coffee"
},
"data": {
"contact": {
"id": "9d2e…",
"display_name": "Sam Customer",
"…": "…"
},
"changed": [
"tags",
"lifecycle_stage"
]
},
"test": false
}
lead.submitted — Lead submitted
A Meta Lead Ads form was submitted and saved (answers included).
Recommended: it is ticked by default when you add a webhook. A webhook created with an API key only gets this event when the key may use contacts (use_contacts). Not tied to one connected account, so a key's account list doesn't filter it.
{
"id": "evt_5f2c0f9b6c3e4f0e8f1a2b3c4d5e6f70",
"type": "lead.submitted",
"version": 1,
"created_at": "2026-10-18T10:12:03.402115+00:00",
"organization": {
"id": "…"
},
"workspace": {
"id": "…",
"name": "Acme Coffee"
},
"data": {
"lead": {
"id": "5c3d…",
"leadgen_id": "123456789",
"form_id": "987…",
"form_name": "Autumn offer",
"ad_id": "238…",
"ad_name": "Autumn video",
"campaign_name": "Autumn",
"platform": "fb",
"is_organic": false,
"consent_given": true,
"answers": {
"full_name": "Sam Customer",
"email": "sam@example.com"
},
"contact_id": "9d2e…",
"submitted_at": "…"
}
},
"test": false
}
Workflows
workflow.run.failed — Workflow run failed
A workflow run stopped with an error (dry runs excluded).
Recommended: it is ticked by default when you add a webhook. A webhook created with an API key only gets this event when the key may use workflows (use_workflows). Not tied to one connected account, so a key's account list doesn't filter it.
{
"id": "evt_5f2c0f9b6c3e4f0e8f1a2b3c4d5e6f70",
"type": "workflow.run.failed",
"version": 1,
"created_at": "2026-10-18T10:12:03.402115+00:00",
"organization": {
"id": "…"
},
"workspace": {
"id": "…",
"name": "Acme Coffee"
},
"data": {
"workflow": {
"id": "1d0f…",
"name": "Welcome new leads",
"url": "https://app.example.com/…"
},
"run": {
"id": "8a7b…",
"status": "failed",
"trigger_type": "event",
"error": "Google Sheets refused the request.",
"version_number": 3,
"started_at": "…",
"completed_at": "…"
}
},
"test": false
}
Test
test — Test event
Sent when you press "Send test" (or call the test endpoint). test is true, so you can ignore it safely in production code.
{
"id": "evt_5f2c0f9b6c3e4f0e8f1a2b3c4d5e6f70",
"type": "test",
"version": 1,
"created_at": "2026-10-18T10:12:03.402115+00:00",
"organization": {
"id": "…"
},
"workspace": {
"id": "…",
"name": "Acme Coffee"
},
"data": {
"message": "This is a test event. Events you subscribed to will look like this.",
"subscription": {
"id": "…",
"name": "CRM"
},
"sent_by": {
"id": "…",
"name": "Olivia Owner"
}
},
"test": true
}