Webhooks — both directions.

Overview

Webhooks are the most flexible integration. They cover use cases the SDK and channel integrations don't: bridging into a custom workflow, syncing into a CRM, triggering an email, exporting to a data warehouse, or just powering an internal Slack notification.

Two flavours, both covered on this page:

• Inbound (you → Janore). POST a JSON payload to Janore from any HTTP-capable tool (Zapier, Make, a Bash script). Janore replies with a translation/response, the same way the chat widget does.
• Outbound (Janore → you). Janore POSTs every conversation event to your server in real time. Useful for syncing into your CRM, triggering downstream workflows, or auditing every message your assistant sends.

Inbound — call Janore from anything

When you don't want to write SDK code or store an API key in your tool, the inbound webhook is the simplest path. Optional shared-secret Bearer auth.

Enable the channel

Open the dashboard and connect the channel. Optionally set a verify token — a shared secret you'll send as a Bearer header. Skip it for fully open access. Dashboard → Channels → Generic Webhook → Connect.

POST a message

1POST https://janore.com/api/v1/channels/webhook/{ASSISTANT_ID}
2Content-Type: application/json
3Authorization: Bearer {VERIFY_TOKEN}        (optional)
4 
5{
6  "session_id": "any-string",
7  "message": "Hello",
8  "language": "en"
9}

session_id is any stable string per user. language is optional — Janore auto-detects if omitted. The Authorization header is required only if you set a verify token.

Response shape

1{
2  "reply": "Hello! …",
3  "suggestedActions": [
4    { "label": "View pricing", "type": "link", "payload": "/pricing" }
5  ],
6  "conversationId": "uuid",
7  "messageId": "uuid"
8}

Outbound — receive Janore events

Add a webhook URL in Settings → Outbound webhooks. Janore POSTs every event in real time, signed with HMAC-SHA256 so you can verify the request is genuine.

Event types

• conversation.created — a new visitor session started.
• message.received — a visitor message hit the pipeline (content truncated to 500 chars).
• conversation.escalated — the assistant handed off to a human.
• conversation.resolved — the operator marked the conversation done (data-only for now).
• tag.added — an operator tagged the conversation.
• webhook.test — fired manually from the dashboard Test button.

Delivery contract

• HTTP POST, Content-Type: application/json.
• 5-second timeout, fire-and-forget.
• No automatic retries (v0). Make your endpoint idempotent — every event carries a unique event_id UUID.
• Headers: X-Factory-Signature (Stripe-style), X-Factory-Event, X-Factory-Event-Id.

Body schema

1{
2  "event": "conversation.created",
3  "event_id": "9b1d73e8-...-a4c1",
4  "timestamp": 1714502400,
5  "payload": { /* event-specific, see below */ }
6}

1// conversation.created
2{ "conversation_id": "...", "session_id": "...", "channel": "web", "language": "fr" }
3 
4// message.received
5{ "conversation_id": "...", "role": "user", "content": "Hello…", "channel": "web", "language": "en" }
6 
7// conversation.escalated
8{ "conversation_id": "...", "reason": "user asked for human", "lead_score": 0.8, "language": "fr" }
9 
10// conversation.resolved
11{ "conversation_id": "...", "resolved_by": "operator-uuid" }
12 
13// tag.added
14{ "conversation_id": "...", "tag": "lead-hot", "color": null }
15 
16// webhook.test
17{ "ping": "hello" }

Verifying the signature (Node)

1import { createHmac, timingSafeEqual } from 'node:crypto';
2 
3export function verifyJanoreSignature(rawBody: string, header: string, secret: string): boolean {
4  // header: "t=<unix>,v1=<hex>"
5  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
6  if (!parts.t || !parts.v1) return false;
7  const expected = createHmac('sha256', secret)
8    .update(`${parts.t}.${rawBody}`)
9    .digest('hex');
10  const a = Buffer.from(expected, 'hex');
11  const b = Buffer.from(parts.v1, 'hex');
12  if (a.length !== b.length) return false;
13  return timingSafeEqual(a, b);
14}

Verifying the signature (Python)

1import hmac, hashlib
2 
3def verify_janore_signature(raw_body: bytes, header: str, secret: str) -> bool:
4    parts = dict(p.split('=', 1) for p in header.split(','))
5    t, v1 = parts.get('t'), parts.get('v1')
6    if not t or not v1:
7        return False
8    mac = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
9    return hmac.compare_digest(mac, v1)

Example consumer (Express)

1import express from 'express';
2import { verifyJanoreSignature } from './verify';
3 
4const app = express();
5app.post('/janore-events',
6  express.text({ type: 'application/json' }), // capture the raw body
7  (req, res) => {
8    const sig = req.header('X-Factory-Signature') ?? '';
9    if (!verifyJanoreSignature(req.body, sig, process.env.JANORE_WEBHOOK_SECRET!)) {
10      return res.status(401).send('bad signature');
11    }
12    const evt = JSON.parse(req.body);
13    // De-duplicate on evt.event_id — we don't retry but upstream tools sometimes do.
14    console.log('janore event', evt.event, evt.event_id);
15    res.status(200).send('ok');
16  });

Retry policy

v0 sends each event once with a 5-second timeout. There are no automatic retries — if your endpoint is down, that event is gone. Treat events as best-effort notifications, not as a source of truth: every event includes the conversation_id, so you can always fetch the canonical state via the REST API after the fact.

Limits

• Same limit as the REST API: 60 requests/minute per assistant. Higher tiers lift the cap.
• Outbound: at-most-once delivery — we do not retry on 5xx today (planned for v0.7).
• Your endpoint must respond within 5 seconds; longer requests are dropped and logged.

Security & RGPD

Inbound: optional Bearer shared secret in the Authorization header. Outbound: HMAC-SHA256 signature in the X-Factory-Signature header (verification snippets above for Node and Python). All traffic is TLS 1.3.

Troubleshooting

• 401 on outbound consumer. Verify the secret in Settings matches what your code computes against. The signature includes the timestamp prefix t=<unix>. — don't forget the dot.
• Events not arriving. Open Settings → Outbound webhooks → Recent deliveries. Failed responses (5xx, timeout) are listed with the response body.
• Same event arrived twice. Upstream tools occasionally re-emit. De-duplicate on event_id (uuid) — Janore generates a stable id per event.