Elaras/

Webhooks

Elaras uses webhooks in two distinct places. They look similar but serve different purposes.

FlavourWhen it firesWhere you configure it
Event webhooksElaras tells your server something happened (message, lead captured, session started…)Developer > Webhooks
Skill webhooksYour server receives a tool call from the agent during a conversationEach skill's Endpoint URL field

Both use the same HMAC-SHA256 signing scheme and the same X-Elaras-Signature header. Both are verifiable with the verifyWebhookSignature helper in @elaras/sdk-node.

Skill webhooks (tool calls from the agent)

When an AI agent decides to call one of your custom skills, Elaras POSTs this payload to the skill's configured endpoint:

{
  "skill": "book_appointment",
  "params": {
    "name": "Vesper Halloway",
    "slot": "2026-10-20 14:00"
  },
  "session": {
    "id": "f7a3...",
    "lead_name": "Vesper Halloway",
    "lead_email": "vesper@example.com",
    "external": {
      "user_id": "u_42",
      "profile_id": "tenant:acme",
      "org_id": "org_xyz"
    }
  }
}

The session.external block carries the identity passthroughs passed at session creation (external_user_id / external_profile_id / external_org_id). This lets your skill endpoint tie the chat conversation back to the end-user in your own system.

  • Null fields inside session.external are omitted rather than sent as explicit null
  • If all three are null, session.external is omitted entirely
  • Internal Elaras session metadata (lead-capture state, flow state, etc.) is never forwarded

Your endpoint should return 200 with a JSON body. That body becomes the tool result the LLM sees — it can use whatever you return to compose its reply.

Returning data

Return any JSON object. The LLM will reason over it directly:

{ "status": "confirmed", "booking_ref": "BK-9921", "slot": "2026-10-20 14:00" }

Handling errors and access control

Do not return HTTP error codes (4xx/5xx) for application-level errors. If Elaras receives a non-2xx response, the skill is silently skipped — the LLM carries on without the data and the user sees nothing.

Instead, return 200 with an error payload in the body so the LLM can relay the situation naturally in the chat:

{ "status": "unauthorized", "message": "You don't have access to this content." }
{ "status": "not_found", "message": "No booking found for that reference." }

The LLM will read the message field and tell the user something meaningful rather than silently skipping.

Reserve actual HTTP errors for infrastructure failures (your server is genuinely down, middleware rejected the request before your code ran). Those are correctly silent-skipped — the user shouldn't see an error about your infrastructure.

Webhooks let Elaras notify your server when events happen in real time. Use them to sync conversations to your CRM, trigger automations, notify your team in Slack, or update your database when a lead is captured.

How webhooks work

  1. You register a webhook URL in the Elaras dashboard under Developer > Webhooks.
  2. When an event occurs, Elaras sends a POST request to your URL with a JSON payload and a signature header.
  3. Your server verifies the signature and processes the event.
  4. You respond with any 2xx status within 15 seconds.

If your server does not respond with 2xx, Elaras retries the delivery.

Configuring webhooks

Go to Developer > Webhooks in the Elaras dashboard and click Add webhook:

FieldDescription
URLYour publicly reachable HTTPS endpoint
EventsChoose which events trigger this webhook (or select "All events")

Elaras generates a signing secret automatically when you create the webhook. Copy it from the dashboard — it is only shown once. Store it as an environment variable on your server.

Events

message.created

Fired when an AI response is saved to a session.

{
  "event": "message.created",
  "timestamp": "2026-07-24T10:30:00+00:00",
  "data": {
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "chatbot_id": 1,
    "message": {
      "id": 42,
      "role": "assistant",
      "content": "We are open Monday to Friday, 9am to 5pm.",
      "credits_used": 3
    }
  }
}

session.started

Fired when a new session sends its first message.

{
  "event": "session.started",
  "timestamp": "2026-07-24T10:29:55+00:00",
  "data": {
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "chatbot_id": 1
  }
}

lead.captured

Fired when a user submits their contact details via the lead capture form or the SDK's submitLead() method.

{
  "event": "lead.captured",
  "timestamp": "2026-07-24T10:31:00+00:00",
  "data": {
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "chatbot_id": 1,
    "name": "Jordan",
    "email": "user@example.com"
  }
}

human.takeover

Fired when an operator claims a conversation from the inbox.

{
  "event": "human.takeover",
  "timestamp": "2026-07-24T10:32:00+00:00",
  "data": {
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "chatbot_id": 1,
    "operator_name": "Alice",
    "taken_over_by": "alice@example.com"
  }
}

conversation.flagged

Fired when the AI flags a conversation for review.

{
  "event": "conversation.flagged",
  "timestamp": "2026-07-24T10:33:00+00:00",
  "data": {
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "chatbot_id": 1,
    "flag_id": 7,
    "category": "off_topic",
    "severity": "medium",
    "reason": "User is asking for legal advice outside the agent's scope."
  }
}

Payload structure

Every webhook payload shares this top-level shape:

FieldTypeDescription
eventstringEvent type
timestampstringISO 8601 timestamp of when the event was dispatched
dataobjectEvent-specific data

Elaras also enriches data with session context where available:

FieldDescription
session_urlLink to the conversation in the Elaras dashboard
lead_nameVisitor's name if captured
lead_emailVisitor's email if captured
first_user_messageFirst message the visitor sent (up to 200 chars)
last_user_messageMost recent message the visitor sent (up to 200 chars)

Signature verification

Elaras signs every webhook request with HMAC-SHA256 using the webhook secret. The signature is in the X-Elaras-Signature header:

X-Elaras-Signature: sha256=a1b2c3d4e5f6...

A second header, X-Elaras-Event, contains the event name as a convenience for routing.

Always verify the signature before processing a webhook. This prevents malicious third parties from sending fake events to your endpoint.

Node.js

import crypto from 'crypto';
import express from 'express';

const app = express();

app.post('/webhooks/elaras', express.raw({type: 'application/json'}), (req, res) => {
  const signature     = req.headers['x-elaras-signature'];
  const webhookSecret = process.env.ELARAS_WEBHOOK_SECRET;

  const expected = 'sha256=' + crypto
    .createHmac('sha256', webhookSecret)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }

  const payload = JSON.parse(req.body);

  switch (payload.event) {
    case 'message.created':
      console.log('New message:', payload.data.message.content);
      break;

    case 'session.started':
      console.log('New session:', payload.data.session_id);
      break;

    case 'lead.captured':
      console.log('Lead:', payload.data.email);
      // e.g. add to your CRM
      break;
  }

  res.status(200).send('ok');
});

PHP

<?php

$rawBody       = file_get_contents('php://input');
$signature     = $_SERVER['HTTP_X_ELARAS_SIGNATURE'] ?? '';
$webhookSecret = getenv('ELARAS_WEBHOOK_SECRET');

$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $webhookSecret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    echo 'Invalid signature';
    exit;
}

$payload = json_decode($rawBody, true);

switch ($payload['event']) {
    case 'message.created':
        error_log('New message: ' . $payload['data']['message']['content']);
        break;

    case 'session.started':
        error_log('New session: ' . $payload['data']['session_id']);
        break;

    case 'lead.captured':
        error_log('Lead: ' . $payload['data']['email']);
        // Add to your CRM...
        break;
}

http_response_code(200);
echo 'ok';

Retry behaviour

If your endpoint does not return a 2xx response (or times out after 15 seconds), Elaras automatically retries:

AttemptDelay after previous attempt
1st retry1 minute
2nd retry5 minutes

After 3 total attempts (1 initial + 2 retries), the delivery is marked as failed and no further attempts are made.

Responding

  • Respond with any 2xx status code (200, 204, etc.) to acknowledge receipt.
  • Respond within 15 seconds — process the event asynchronously if needed (queue it, then respond 200 immediately).
  • The response body is ignored by Elaras.

Security tips

  • Store your webhook secret in an environment variable — never hardcode it.
  • Use hash_equals() / timingSafeEqual() for comparison — never === or ==. This prevents timing attacks.
  • Only accept HTTPS endpoints.
  • Use a dedicated endpoint for Elaras webhooks rather than a shared route.