> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roark.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks
> Receive real-time notifications when call analysis completes or fails
## Overview
Webhooks allow you to receive real-time HTTP notifications when events occur in Roark. Instead of polling for updates, Roark will automatically send event data to your specified endpoint whenever a call analysis completes or fails.
***
## Webhook Events
Roark currently supports the following webhook events:
### `call.analysis.completed`
Triggered when a call analysis has successfully completed processing.
**Event Payload:**
* `callId` - Unique identifier for the call
* `callAnalysisJobId` - ID of the completed analysis job
* `projectId` - ID of the project containing the call
### `call.analysis.failed`
Triggered when a call analysis fails to complete.
**Event Payload:**
* `callId` - Unique identifier for the call
* `callAnalysisJobId` - ID of the failed analysis job
* `projectId` - ID of the project containing the call
* `errorMessage` - Description of the failure (optional)
***
## Setting Up Webhooks
Go to your workspace settings and select the Webhooks section
Enter the URL where you want to receive webhook events
Choose which events you want to subscribe to:
* Call Analysis Completed
* Call Analysis Failed
Use the "Send Test Event" button to verify your endpoint is working correctly
***
## Testing Webhooks
You can send test events to verify your webhook integration is working properly:
1. **Send Test Event** - Click the "Send Test Event" button next to your webhook endpoint
2. **Verify Receipt** - Check that your endpoint received the test payload
3. **Validate Handling** - Ensure your application processes the test event correctly
Test events contain sample data that matches the structure of real webhook events, allowing you to validate your integration before going live.
***
## Webhook Security
### Signature Verification
All webhook requests from Roark include a signature header that you can use to verify the request authenticity:
```
X-Roark-Signature:
```
Always validate webhook signatures in production to ensure requests are coming from Roark and haven't been tampered with.
### Best Practices
* **Use HTTPS** - Only accept webhooks over secure HTTPS connections
* **Verify Signatures** - Always validate the webhook signature
* **Respond Quickly** - Return a 200 OK response within 5 seconds
* **Process Async** - Handle webhook processing in background jobs
* **Implement Retries** - Handle temporary failures gracefully
***
## Webhook Delivery
### Retry Logic
If your endpoint fails to respond with a 2xx status code, Roark will retry the webhook delivery:
* **Retry Attempts**: Up to 3 retries
* **Retry Schedule**: Exponential backoff (1 min, 10 min, 1 hour)
* **Timeout**: 5 seconds per request
### Response Requirements
Your endpoint should:
* Return a `200 OK` status code to acknowledge receipt
* Respond within 5 seconds
* Process the webhook payload asynchronously if needed
***
## Event Payload Structure
All webhook events follow a consistent structure with an `event` name, API `version`, `timestamp`, and event-specific `data`.
### Call Analysis Completed
```json theme={null}
{
"event": "call.analysis.completed",
"version": "1.0",
"timestamp": "2025-11-21T10:30:00Z",
"data": {
"callId": "call_abc123",
"callAnalysisJobId": "job_xyz789",
"projectId": "proj_def456"
}
}
```
### Call Analysis Failed
```json theme={null}
{
"event": "call.analysis.failed",
"version": "1.0",
"timestamp": "2025-11-21T10:30:00Z",
"data": {
"callId": "call_abc123",
"callAnalysisJobId": "job_xyz789",
"projectId": "proj_def456",
"errorMessage": "Analysis timeout exceeded"
}
}
```
***
## Use Cases
### Real-time Notifications
Send alerts to your team when critical calls fail analysis:
```javascript theme={null}
app.post('/webhooks/roark', (req, res) => {
const { event, data } = req.body;
if (event === 'call.analysis.failed') {
sendSlackAlert(
`Call ${data.callId} analysis failed: ${data.errorMessage || 'Unknown error'}`
);
}
res.sendStatus(200);
});
```
### Data Synchronization
Keep your internal systems in sync with Roark analysis results:
```python theme={null}
@app.route('/webhooks/roark', methods=['POST'])
def handle_webhook():
payload = request.json
if payload['event'] == 'call.analysis.completed':
# Fetch full call details and update your database
call_id = payload['data']['callId']
update_call_analytics(call_id=call_id)
return '', 200
```
### Workflow Automation
Trigger downstream processes when analysis completes:
```javascript theme={null}
async function handleWebhook(event) {
if (event.event === 'call.analysis.completed') {
const { callId, projectId } = event.data;
// Trigger follow-up actions
await updateCRM(callId, projectId);
await sendCustomerSurvey(callId);
await notifyQATeam(callId);
}
}
```
***
## Troubleshooting
### Webhook Not Received
* **Check URL** - Ensure your endpoint URL is correct and accessible
* **Verify HTTPS** - Confirm you're using HTTPS (HTTP not supported)
* **Check Firewall** - Ensure your firewall allows incoming requests from Roark
* **Review Logs** - Check your server logs for incoming requests
### Delivery Failures
* **Response Time** - Ensure your endpoint responds within 5 seconds
* **Status Codes** - Return 2xx status codes to acknowledge receipt
* **Error Handling** - Check your endpoint for exceptions or crashes
### Missing Events
* **Event Subscriptions** - Verify you're subscribed to the correct events
* **Endpoint Status** - Check if your webhook endpoint is marked as active
* **Delivery History** - Review the webhook delivery logs in your Roark dashboard
***
## Next Steps
Explore the Roark API
Build custom integrations
Monitor calls in real-time
Get help with webhooks