Skip to main content
POST
/
v1
/
webhooks
curl -X POST https://api.ringyo.ai/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/ringyo",
    "events": ["call.completed", "call.recording.ready"],
    "description": "Production webhook"
  }'

{
  "id": "wh_abc123",
  "url": "https://your-app.com/webhooks/ringyo",
  "events": ["call.completed", "call.recording.ready"],
  "secret": "whsec_a1b2c3d4e5f6g7h8i9j0...",
  "description": "Production webhook",
  "status": "active",
  "metadata": {},
  "created_at": "2024-01-15T10:30:00Z"
}

​
Request

Create a new webhook endpoint to receive real-time events from Ringyo AI.

​
Headers

​
Authorization
string
required
Bearer token for authentication. Format: Bearer YOUR_API_KEY
​
Content-Type
string
required
Must be application/json

​
Body Parameters

​
url
string
required
The HTTPS URL to receive webhook events
​
events
array
required
Array of event types to subscribe to. Use ["*"] for all events.Available events:
  • call.started - Call has been initiated
  • call.ringing - Call is ringing
  • call.answered - Call was answered
  • call.completed - Call ended successfully
  • call.failed - Call failed
  • call.recording.ready - Recording is available
  • call.transcript.ready - Transcript is available
  • agent.created - New agent created
  • agent.updated - Agent was updated
  • agent.deleted - Agent was deleted
​
secret
string
A secret key for signing webhook payloads. Auto-generated if not provided.
​
description
string
A description for this webhook endpoint
​
metadata
object
Custom key-value pairs for your reference

​
Response

​
id
string
Unique identifier for the webhook
​
url
string
The webhook URL
​
events
array
Subscribed event types
​
secret
string
The webhook signing secret (only shown on creation)
​
status
string
Webhook status: active, inactive, failing
​
created_at
string
ISO 8601 timestamp
curl -X POST https://api.ringyo.ai/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/ringyo",
    "events": ["call.completed", "call.recording.ready"],
    "description": "Production webhook"
  }'

{
  "id": "wh_abc123",
  "url": "https://your-app.com/webhooks/ringyo",
  "events": ["call.completed", "call.recording.ready"],
  "secret": "whsec_a1b2c3d4e5f6g7h8i9j0...",
  "description": "Production webhook",
  "status": "active",
  "metadata": {},
  "created_at": "2024-01-15T10:30:00Z"
}

​
Verifying Webhooks

Use the secret to verify incoming webhooks: 
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler:
app.post('/webhooks/ringyo', (req, res) => {
  const signature = req.headers['x-ringyo-signature'];
  
  if (!verifyWebhook(JSON.stringify(req.body), signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook...
});

​
Error Codes

CodeDescription
invalid_urlURL must be a valid HTTPS endpoint
invalid_eventsOne or more event types are invalid
webhook_limit_reachedMaximum webhooks for your plan
url_unreachableCould not reach the webhook URL