The API reference moved here from eksis.io/developers.

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 secret right away. It is returned once.
  • A workspace has up to 3 endpoints on Pro Eksis and Super Eksis.
  • The URL must use https and resolve to a public address. Private networks, localhost, and addresses on eksis.io are refused with webhook.url_private. While developing, use a tunnel such as cloudflared or ngrok.
  • 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.

EventSent whenChannel id
message.receivedA DM or a story reply arriveddata.conversation.channelId
comment.receivedSomeone else commenteddata.channelId
post.target.publishedA post went out on one channeldata.target.channelId
post.target.failedPublishing to one channel failed for gooddata.target.channelId
channel.unhealthyA channel's connection broke and its posts are helddata.channel.id
channel.disconnectedA channel was disconnected from the workspacedata.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:

  1. Verify the signature against the raw body, before parsing it. Reject a webhook-timestamp more than five minutes from your clock.
  2. Drop duplicates. Delivery is at least once. Keep the webhook-id values you have handled and skip repeats.
  3. Answer 2xx within 10 seconds. A slower answer counts as a failure and the event comes again.
  4. 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 Gone disables 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.test right 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.

On this page