Receive events
Get DMs, comments, publishing results, and channel problems pushed to your server, and route each one to the right customer.
With many customers in one workspace, polling every conversation does not scale. A webhook endpoint gets each new DM, comment, and publishing result as it happens, and every event names the channel it belongs to. This page covers what a product built on eksis needs from webhooks. The Webhooks reference has the full details.
Add an endpoint
Create the endpoint once, from the app or with an admin key:
curl -X POST https://api.eksis.io/v1/webhooks \
-H "Authorization: Bearer $EKSIS_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-app.example/eksis/webhooks",
"description": "Customer events",
"events": ["message.received", "comment.received", "channel.unhealthy", "channel.disconnected"]
}'- Store the
secretright away. It is returned once. - A workspace has up to 3 endpoints on Pro Eksis and Super Eksis.
- The URL must use
httpsand resolve to a public address. Private networks,localhost, and addresses oneksis.ioare refused withwebhook.url_private. While developing, use a tunnel such ascloudflaredorngrok. - An endpoint receives only the events it subscribed to. Event types added to eksis later are never added to it on their own.
Reference: Create a webhook endpoint.
Route each event to a customer
Every event has workspaceId and a channel id. Look the channel id up in your customer table to find whose event it is.
| Event | Sent when | Channel id |
|---|---|---|
message.received | A DM or a story reply arrived | data.conversation.channelId |
comment.received | Someone else commented | data.channelId |
post.target.published | A post went out on one channel | data.target.channelId |
post.target.failed | Publishing to one channel failed for good | data.target.channelId |
channel.unhealthy | A channel's connection broke and its posts are held | data.channel.id |
channel.disconnected | A channel was disconnected from the workspace | data.channel.id |
eksis sends events only for things other people did. Your own comments and the DMs you send are not echoed back as comment.received or message.received.
Handle a delivery
Every delivery is a POST with a JSON body and three signature headers in the Standard Webhooks format. A handler that holds up under retries does four things in this order:
- Verify the signature against the raw body, before parsing it. Reject a
webhook-timestampmore than five minutes from your clock. - Drop duplicates. Delivery is at least once. Keep the
webhook-idvalues you have handled and skip repeats. - Answer
2xxwithin 10 seconds. A slower answer counts as a failure and the event comes again. - Do the work afterwards, from a queue or a background task. Searching a catalog and replying to a DM can take longer than 10 seconds.
import { createServer } from 'node:http';
import { verifyEksisWebhook } from './verify-eksis-webhook.js'; // from the Webhooks page
const seen = new Set(); // use your database in production
createServer(async (req, res) => {
const chunks = [];
for await (const chunk of req) chunks.push(chunk);
const rawBody = Buffer.concat(chunks).toString('utf8');
if (!verifyEksisWebhook(rawBody, req.headers, process.env.EKSIS_WEBHOOK_SECRET)) {
res.writeHead(401).end();
return;
}
const id = req.headers['webhook-id'];
res.writeHead(204).end(); // acknowledge first
if (seen.has(id)) return;
seen.add(id);
const event = JSON.parse(rawBody);
setImmediate(() => handleEvent(event)); // your own code, run after the answer
}).listen(3000);The verifyEksisWebhook function is on the Webhooks page, in Node.js and Python. A full handler with every step is in Example: a DM bot.
When deliveries fail
- A failed attempt is retried after 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour, 3 hours, 6 hours, and 12 hours, give or take 10 percent: nine attempts over about 23 hours.
- Events can arrive out of order. Compare
createdAt, or read the resource from the API when order matters. - An endpoint that keeps failing for 72 hours, with at least 10 failed attempts, is disabled. Answering
410 Gonedisables it at once. Turn it back on in the app or with Update a webhook endpoint. - Each endpoint keeps its deliveries for 14 days: List deliveries.
Delivery is at least once, not exactly once, and an endpoint that was down can miss events. Read the API on a schedule as a safety net, for example GET /v1/conversations, whose unreadCount and lastMessageAt show conversations with messages you have not handled yet.
Test and rotate
- Send a test event delivers
webhook.testright away. Test events are never retried. - Rotate the signing secret returns a new secret once. For 24 hours eksis signs with both the old and the new one, so you can deploy the new secret without losing events.