Skip to main content

​
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

1

Navigate to Webhooks

Go to your workspace settings and select the Webhooks section
2

Add Endpoint

Enter the URL where you want to receive webhook events
3

Select Events

Choose which events you want to subscribe to:
  • Call Analysis Completed
  • Call Analysis Failed
4

Test Your Webhook

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: <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

{
  "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

{
  "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: 
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: 
@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: 
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

API Reference

Explore the Roark API

Custom Integrations

Build custom integrations

Live Monitoring

Monitor calls in real-time

Support

Get help with webhooks