What you will learn
- Understand the architectural difference between Functions and Webhooks.
- Configure the Webhook Skill in raia Command.
- Understand the structure of the default raia webhook payload.
- Choose the right integration pattern for your specific use case.
Functions vs Webhooks: Direction Matters
In the previous module, we covered Functions. Functions are a pull mechanism — the agent pauses a conversation, asks an external system for data, and pulls that data back in to formulate an answer.
Webhooks are the opposite. They are a push mechanism. The agent does not wait for a response; it simply fires data out to an external system when a specific event occurs.
The two webhook triggers
Event
onMessageEnd
Fires every time the agent sends a reply. Ideal for real-time dashboards or live syncs.
Event
onThreadEnd
Fires when a conversation is considered complete (typically after 6 minutes of inactivity). Ideal for logging full transcripts to a CRM or triggering post-conversation automation.
What the Payload Contains
When a webhook fires, raia automatically sends a rich JSON payload to your specified endpoint. You do not need to write code to format this payload; it is generated natively by the platform.
The payload includes everything an external system needs to process the event:
01
Agent Identity
Which agent handled the conversation (agent_name).
02
Thread Context
The unique identifier for the conversation (thread_id) and the channel it occurred on (channel).
03
User Data
Any collected information about the user (user_name, user_email, user_phone).
04
Message Content
The actual text of the message.
05
Metadata
Timestamps, source tags, and scoring data (if the Scoring Skill is enabled).
The Three Integration Patterns
When architecting an agentic solution, you generally choose between three integration patterns based on where the data needs to go and who initiates the action.
Pattern 01
Push data out after conversation (Webhook)
Use case: You want to log every completed Live Chat conversation as a ticket in Zendesk or push lead data to HubSpot.
How it works: Configure a webhook in raia to fire onThreadEnd and point it at a Zapier or n8n webhook URL, which then formats the data and pushes it to your CRM.
Pattern 02
Pull data in during conversation (Function)
Use case: A user asks, "Has my payment cleared?"
How it works: The agent triggers a Function, calls your internal billing API, retrieves the status, and replies to the user in real-time.
Pattern 03
Trigger agent from external system (API)
Use case: A customer submits a complex support form on your website, and you want the AI to draft the initial response before a human sees it.
How it works: Your backend calls the raia API (/api/conversations/start), passes the form data as context, and retrieves the agent's generated reply to display in your support portal.
Frequently Asked Questions
Can I customize the JSON payload sent by the webhook?
By default, raia sends a standardized, comprehensive payload. To customize or filter the fields, point the webhook at an intermediary tool like Zapier, Make, or n8n, which can shape the data before passing it to its final destination.
What happens if my endpoint is down when the webhook fires?
Webhook delivery status is tracked in the thread metadata. If an endpoint times out or returns an error, admins can view the failure in Mission Control and manually retry or debug the connection.
Do I need to worry about PII in webhooks?
Yes. Because webhooks push full conversation data, ensure your receiving endpoint is secure (HTTPS) and that you sanitize or securely store any PII (emails, phone numbers) on your backend according to your company's compliance policies.