A robust Express.js web service designed to handle webhook events from AVR Core. This service provides a clean and intuitive API for processing various types of events generated during voice interactions.
- Express.js based web service
- Security middleware (Helmet, CORS, Rate Limiting)
- Comprehensive logging for all events
- Request validation and error handling
- Event-specific handlers for different webhook types
- Health check endpoint
- Graceful shutdown handling
- Install dependencies:
npm install- Copy environment configuration:
cp .env.example .env-
Configure your environment variables in
.env -
Start the service:
# Development
npm run start:dev
# Production
npm startGET /health
Returns the service health status and version information.
Response:
{
"status": "healthy",
"timestamp": "2024-01-15T10:30:00.000Z",
"service": "avr-webhook",
"version": "1.0.0"
}POST /events
Main endpoint for receiving webhook events from AVR Core.
Request Body:
{
"uuid": "unique-event-identifier",
"type": "event-type",
"timestamp": "2024-01-15T10:30:00.000Z",
"payload": {
// Event-specific data
}
}Response:
{
"success": true,
"message": "Event processed successfully",
"eventId": "unique-event-identifier",
"processedAt": "2024-01-15T10:30:00.000Z"
}| Event Type | Description | Payload Example |
|---|---|---|
call_started |
Call initiation | {} |
call_ended |
Call termination | {} |
transcription |
Speech-to-text result | { role, text } |
interruption |
User interruption | {} |
dtmf_digit |
User digit | { digit } |
error |
Error occurred | { message } |
| Variable | Description | Default |
|---|---|---|
PORT |
Server port | 3000 |
NODE_ENV |
Environment | development |
ALLOWED_ORIGINS |
CORS allowed origins | * |
RATE_LIMIT_MAX |
Max requests per IP per 15min | 100 |
WEBHOOK_SECRET |
Webhook signature secret | - |
- Helmet: Security headers
- CORS: Cross-origin resource sharing
- Rate Limiting: Prevents abuse (100 requests per 15 minutes per IP)
- Request Validation: Validates required fields
- Error Handling: Comprehensive error responses
The service includes dedicated handlers for each event type:
- Call Events: Track call lifecycle
- Transcription Events: Process speech-to-text results
- LLM Events: Handle AI responses
- TTS Events: Manage text-to-speech completion
- Error Events: Log and alert on errors
- Agent Events: Track agent connections
- User Input Events: Process user interactions
- System Events: Handle system messages
npm run start:devUses nodemon for automatic restarts on file changes.
# Build image
npm run dc:build
# Push to registry
npm run dc:pushThe service provides comprehensive error handling:
- 400 Bad Request: Missing required fields
- 404 Not Found: Invalid endpoints
- 429 Too Many Requests: Rate limit exceeded
- 500 Internal Server Error: Processing errors
All errors include timestamps and descriptive messages.
The service logs:
- All incoming requests with IP addresses
- Event processing details
- Errors with full stack traces
- Service startup and shutdown events
Configure AVR Core to send webhooks to this service:
# In avr-core service .env
WEBHOOK_URL=http://localhost:3000/events
WEBHOOK_SECRET=your-webhook-secret-here
WEBHOOK_TIMEOUT=3000
WEBHOOK_RETRY=3- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
- GitHub: https://github.com/agentvoiceresponse - Report issues, contribute code.
- Discord: https://discord.gg/DFTU69Hg74 - Join the community discussion.
- Docker Hub: https://hub.docker.com/u/agentvoiceresponse - Find Docker images.
- NPM: https://www.npmjs.com/~agentvoiceresponse - Browse our packages.
- Wiki: https://wiki.agentvoiceresponse.com/en/home - Project documentation and guides.
AVR is free and open-source. If you find it valuable, consider supporting its development:
MIT License - see the LICENSE file for details.