Webhooks

Receive real-time notifications when events occur in your Ragtime assistant conversations. Use webhooks to integrate with N8N, Zapier, Make, or any HTTP-capable automation platform.

Setup

1. Open the project, then go to Dashboard → Integrations → Webhooks.
2. Click Add Webhook and enter the URL of your endpoint (e.g. your N8N webhook trigger URL).
3. Select which events you want to receive.
4. Copy the signing secret — it’s shown only once. Store it securely.

Event Types

Event	Description
session_started	A new conversation session begins (greeting generated).
message	A user sends a message and the assistant responds.
session_ended	A conversation session ends (natural, idle timeout, user-initiated, etc.).
action_executed	An action ran during the conversation.
knowledge_used	The assistant cited knowledge base sources in a response.
source_ingested	A knowledge base source finished processing.
finding_opened	The daily Insights check found something new for the team.
finding_returned	A deferred or declined finding needs the team again.
finding_reopened	A resolved finding came back.
finding_trending	An open finding started rising against the 14 days before.

Payload Format

All webhook deliveries are POST requests with a JSON body:

{
 "event": "message",
 "timestamp": "2026-03-25T12:00:00.000Z",
 "projectId": "a1b2c3d4-...",
 "isLive": true,
 "data": {
  // event-specific fields
 }
}

The isLive field is true when the event originates from a published (live) assistant URL, and false when it comes from a preview URL. Use this to filter out test traffic in your automations.

session_started

{
 "event": "session_started",
 "timestamp": "...",
 "projectId": "...",
 "isLive": true,
 "data": {
  "greeting": "Hello! How can I help you today?"
 }
}

message

{
 "event": "message",
 "timestamp": "...",
 "projectId": "...",
 "isLive": true,
 "data": {
  "userMessage": "What are your pricing plans?",
  "response": "We offer three tiers...",
  "emotion": "neutral",
  "confidence": "0.92",
  "language": "en",
  "usedKnowledgeBase": true,
  "executedActions": []
 }
}

session_ended

{
 "event": "session_ended",
 "timestamp": "...",
 "projectId": "...",
 "isLive": true,
 "data": {
  "reason": "natural",
  "lastResponse": "Goodbye! Feel free to come back anytime."
 }
}

action_executed

{
 "event": "action_executed",
 "timestamp": "...",
 "projectId": "...",
 "isLive": false,
 "data": {
  "actions": ["book_appointment"]
 }
}

knowledge_used

{
 "event": "knowledge_used",
 "timestamp": "...",
 "projectId": "...",
 "isLive": true,
 "data": {
  "sourceIds": ["a1b2c3d4-...", "e5f6g7h8-..."],
  "count": 2
 }
}

Contains the unique source IDs that were cited to generate the response. Use this to track which knowledge articles are most helpful.

source_ingested

{
 "event": "source_ingested",
 "timestamp": "...",
 "projectId": "...",
 "isLive": true,
 "data": {
  "sourceId": "a1b2c3d4-...",
  "libraryId": "e5f6g7h8-...",
  "fileName": "pricing.pdf",
  "status": "completed",
  "chunks": { "total": 42, "successful": 42, "failed": 0 }
 }
}

status is completed, or partial when processing finished with warnings (for example, some chunks failed).

Finding events

finding_opened, finding_returned, finding_reopened and finding_trending are sent after the daily Insights findings check, one event per finding, so an automation can open one ticket per finding. data.finding has exactly the shape the findings API returns: the anonymized visitor questions, never conversation IDs.

{
 "event": "finding_opened",
 "timestamp": "...",
 "projectId": "...",
 "isLive": true,
 "data": {
  "finding": {
   "id": "finding-uuid-...",
   "kind": "missing_knowledge",
   "status": "open",
   "title": "Visitors ask: \"Can I bring my dog?\"",
   "volume": 14,
   "questions": ["Can I bring my dog?", "Are pets allowed inside?"],
   "source": null,
   "recommendation": { "lead": "...", "points": ["..."] }
  }
 }
}

Findings raised from generated test data never send an event. A finding_trending event does not change the finding’s status. It fires when an open finding starts rising, so you can raise your own alert.

Verifying Signatures

Every webhook request includes an X-Ragtime-Signature header containing an HMAC-SHA256 signature of the request body, using your webhook’s signing secret.

The header format is: sha256=<hex digest>

Verification example (Node.js)

import crypto from 'node:crypto';

function verifySignature(body, secret, signatureHeader) {
 const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(body).digest('hex');

 return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

// In your webhook handler:
const isValid = verifySignature(
 rawBody,
 process.env.RAGTIME_WEBHOOK_SECRET,
 request.headers['x-ragtime-signature']
);

Verification example (Python)

import hmac, hashlib

def verify_signature(body: bytes, secret: str, signature_header: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Using with N8N

1. In N8N, add a Webhook trigger node.
2. Copy the generated webhook URL (e.g. https://your-n8n.com/webhook/abc123).
3. In Ragtime, create a webhook with that URL and select your desired events.
4. Optionally, add a Header Auth credential in N8N to verify the X-Ragtime-Signature header.
5. Use the incoming data in your N8N workflow — route to CRM, Slack, email, or any other service.

The X-Ragtime-Event header contains the event type, which you can use for conditional routing in your workflow.

Delivery & Retries

• Webhooks are delivered asynchronously and do not block chat responses.
• Each delivery has a 10-second timeout.
• Failed deliveries are retried up to 3 times with exponential backoff (5s, 15s).
• Non-retryable HTTP errors (4xx except 429) are not retried.
• Every delivery attempt is logged. View the delivery history per webhook in Dashboard → Integrations → Webhooks by clicking the History button. The log shows status, HTTP code, duration, retry count, and error details.

Request Headers

Header	Description
Content-Type	application/json
X-Ragtime-Signature	HMAC-SHA256 signature: sha256=<hex>
X-Ragtime-Event	The event type (e.g. message, session_ended)