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. Go to Dashboard → Assistant → Webhooks tab in your project.
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 HTTP action was triggered during the conversation.
knowledge_used	The assistant cited knowledge base sources in a response.

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.

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 → Assistant → 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)