LobeHub Developer Webhooks
Coming soon (#23272). Developer webhooks are not on LobeHub Cloud yet. This page describes the delivery format and signature scheme implemented in that pull request so you can prepare a receiver; names and limits can still change before release.
A webhook endpoint is a URL of yours that LobeHub calls with a signed POST when something happens in your personal space or Workspace: a run finishes, a message is created, a file is parsed. Endpoints are managed through /api/v1/webhooks with the webhook:read and webhook:write scopes, or from Settings → Webhooks in the app, which the same pull request adds.
Manage Endpoints
| Method and path | Purpose |
|---|---|
GET /webhooks | List endpoints (cursor pagination) |
POST /webhooks | Create an endpoint: url, events, optional description and enabled. The response contains the signing secret, shown only here |
GET /webhooks/{id} | Read an endpoint |
PATCH /webhooks/{id} | Change its URL, events, description, or enable it again |
DELETE /webhooks/{id} | Delete it |
POST /webhooks/{id}/rotate-secret | Issue a new signing secret (shown once) |
POST /webhooks/{id}/test | Send a webhook.test event |
GET /webhooks/{id}/deliveries | Delivery log |
POST /webhooks/{id}/deliveries/{deliveryId}/redeliver | Send a past delivery again, with the same event id and body |
A space can have up to 20 endpoints. Subscribing to an event also needs the read scope of its data, for example run:read for run.*; otherwise the request returns 403 insufficient_scope.
Event Catalog
| Event | Sent when | data | Read scope |
|---|---|---|---|
run.started | An Agent run starts | { runId, agentId, topicId } | run:read |
run.completed | A run finishes | Run fields plus assistantMessageId, steps | run:read |
run.failed | A run fails | Run fields plus error | run:read |
run.intervention_requested | A run waits for human approval | { runId, agentId, topicId } | run:read |
message.created | A message is created | { messageId, role, topicId, threadId, agentId } | chat:read |
topic.created | A Topic is created | { topicId, title, agentId } | chat:read |
task.status_changed | A task changes status | { taskId, identifier, status, previousStatus } | agent:read |
goal.status_changed | A goal changes status | { goalId, status, previousStatus } | agent:read |
file.parsed | File parsing finishes | { fileId, name, status: "success" | "error", error } | file:read |
notification.created | A notification is created | { notificationId, category, type, title } | user:read |
webhook.test | You call POST /webhooks/{id}/test | { webhookId, message } | Not subscribable |
Delivery Format
idstays the same across retries and redeliveries. Use it to ignore duplicates.workspaceIdisnullfor events from a personal space.- Only a
2xxanswer counts as delivered. Redirects are not followed. Answer within 10 seconds and do slow work afterwards.
Retries
A failed delivery is attempted up to 6 times in total, waiting 30 seconds, 2 minutes, 8 minutes, 32 minutes, and about 2 hours between attempts. After 5 deliveries in a row fail every attempt, the endpoint is disabled; enable it again with PATCH /webhooks/{id} once the receiver is fixed. Test deliveries are attempted once.
Verify the Signature
Every delivery is signed with the endpoint's secret (whsec_…):
- The HMAC key is the whole secret string, including the
whsec_prefix. - The signed string is the timestamp header, a dot, and the raw request body as received. Parsing and re-serializing the JSON changes it and the signature will not match.
- Reject a timestamp more than 300 seconds away from your clock, so a captured request cannot be replayed later.
- The header can hold several
v1=values separated by spaces or commas, for example right after a secret rotation. Accept the request if any of them matches. - Compare in constant time.
Node.js
With Express, read the raw body before any JSON parser: app.post('/lobehub/webhook', express.raw({ type: 'application/json' }), …), then pass req.body.toString('utf8') and req.headers.
Python
Pass header names in lower case (Flask: {k.lower(): v for k, v in request.headers.items()}) and the body from request.get_data().
With the TypeScript SDK
The same pull request adds verification helpers to @lobehub/sdk. They work with Fetch Headers or Node header objects:
verifyWebhookSignature checks without parsing. Both throw WebhookSignatureVerificationError with a code such as missing_signature, timestamp_out_of_range, or signature_mismatch.
Webhook Channels for Chat Platforms
A separate pull request, #23332 (coming soon), adds a Custom Webhook channel that connects any chat platform to an Agent, plus /api/v1/bots (bot:read, bot:write) to manage bots. Its inbound and outbound messages use the same X-LobeHub-Timestamp and X-LobeHub-Signature scheme, signed with the bot's own secret.