​
Automatic Validation

When you enter a webhook URL in the Beyond Presence dashboard, our system automatically sends a test payload to validate your endpoint:

{
  "event_type": "test",
  "message": "This is a test webhook to validate your endpoint",
  "timestamp": "2024-01-15T10:30:00Z"
}

Your endpoint should return a 200 status code to pass validation.

​
Manual Testing with curl

You can manually test your webhook endpoint using curl to simulate different event types:

​
Testing Message Events

curl -X POST https://your-webhook-url \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "message",
    "call_id": "test_call_123",
    "message": {
      "sender": "user",
      "message": "Test message",
      "sent_at": "2024-01-15T10:30:00Z"
    },
    "call_data": {
      "userName": "Test User",
      "agentId": "test_agent"
    }
  }'

​
Testing Call Ended Events

curl -X POST https://your-webhook-url \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "call_ended",
    "call_id": "test_call_123",
    "evaluation": {
      "topic": "Test Support",
      "user_sentiment": "positive",
      "duration_minutes": 3.2,
      "messages_count": 8
    },
    "messages": [
      {
        "sender": "user",
        "message": "Test message",
        "sent_at": "2024-01-15T10:30:00Z"
      }
    ],
    "user_name": "Test User"
  }'

​
Expected Response

Your webhook should return a 200 status code for successful processing. The response body is optional but can be helpful for debugging:

{
  "status": "success",
  "message": "Webhook received successfully"
}

​
Error Handling

If your webhook returns a non-200 status code or times out (>10 seconds), the webhook delivery will be considered failed. Currently, we don’t implement automatic retries, so ensure your endpoint is reliable.

​
Common Issues

​
Debugging Tips

​
Log Incoming Requests

Always log incoming webhook requests for debugging:

app.post('/webhook', (req, res) => {
  console.log('Webhook received:', {
    headers: req.headers,
    body: req.body,
    timestamp: new Date().toISOString()
  });
  
  // Process webhook...
  
  res.status(200).json({ status: 'success' });
});

​
Validate Event Types

Check the event_type field to handle different event formats:

app.post('/webhook', (req, res) => {
  const { event_type } = req.body;
  
  switch (event_type) {
    case 'test':
      console.log('Test webhook received');
      break;
    case 'message':
      handleMessageEvent(req.body);
      break;
    case 'call_ended':
      handleCallEndedEvent(req.body);
      break;
    default:
      console.log('Unknown event type:', event_type);
  }
  
  res.status(200).json({ status: 'success' });
});

​
Use a Webhook Testing Service

For quick testing, you can use services like:

  • webhook.site - Temporary URLs for testing
  • ngrok - Tunnel your local development server
  • Postman - API testing and development

Development Tip: Use ngrok to expose your local development server for webhook testing:

# Install ngrok
npm install -g ngrok

# Expose your local server
ngrok http 3000

Use the HTTPS URL provided by ngrok as your webhook URL in the dashboard.