Webhooks

Event-Driven Integration

Webhooks are "reverse APIs" where Ayra sends HTTP requests to your systems when events occur—real-time notifications without constant polling.

Understanding Webhooks

Instead of your systems repeatedly asking "has anything happened yet?" (polling), webhooks say "something happened, here's the data" exactly when events occur.

Real-time event notifications

Efficient—no polling overhead

Event-driven architectures

How Webhooks Work

Event occurs in Ayra (call completes, sentiment threshold crossed, keyword detected)

Ayra sends HTTP POST request to your configured webhook URL with event data

Your system receives and processes the event data

Respond with HTTP 200 to confirm receipt

If delivery fails, Ayra retries with exponential backoff

Webhook Payload

Example: Call Completed

{
  "event_id": "evt_abc123",
  "event_type": "call.completed",
  "timestamp": "2025-01-15T15:45:32Z",
  "data": {
    "call_id": "call_xyz789",
    "agent_id": "agent_123",
    "caller_phone": "+15555551234",
    "duration_seconds": 247,
    "transcript": "Full conversation transcript...",
    "sentiment": "positive",
    "outcome": "appointment_booked",
    "metadata": {
      "appointment_time": "2025-01-20T14:00:00Z"
    }
  }
}

Webhook Security

Signature Verification

Webhooks include HMAC signatures to verify requests actually came from Ayra. Always verify signatures before processing:

Extract signature from X-Ayra-Signature header

Compute expected signature using shared secret

Compare received vs expected signature

Process request only if signatures match

Setting Up Webhooks

Endpoint Requirements

Publicly accessible from internet

Use HTTPS (required for security)

Return 200 status on success

Respond within 30 seconds

Handle idempotency (duplicates possible)

Configuration in Ayra

Navigate to Webhooks

Settings → Webhooks

Add Webhook URL

Enter your endpoint URL

Select Events

Choose which events to subscribe to

Configure Secret

Set shared secret for signature verification

Test Webhook

Send test event to verify endpoint works

Available Events

call.startedcall.completedcall.failedtranscript.updatedsentiment.changedkeyword.detectedappointment.bookedticket.created

Usage Scenarios

Real-Time Processing

Process conversations as they happen—analyze, update CRM, trigger workflows immediately.

External System Sync

Keep external systems synchronized—contacts to CRM, appointments to calendar.

Custom Alerting

Build alerts beyond native capabilities—SMS managers, create urgent tickets, trigger escalations.

Data Warehousing

Stream conversation data to analytics platforms, data warehouses, or BI tools.

Advanced Features

Retry Logic

Failed deliveries retry with exponential backoff—immediately, 1 min, 5 min, 15 min, 1 hour, up to 24 hours. Implement idempotent handling for duplicate events.

Event Filtering

Filter events beyond simple type subscription—by agent ID, customer properties, sentiment thresholds, or outcomes. Reduce volume to only relevant events.

Webhook Monitoring

Track delivery success rates, review failed attempts, see latency metrics, and get alerts when endpoints consistently fail.

Best Practices

Respond Quickly

Acknowledge receipt within seconds and return 200. Process heavy work asynchronously after acknowledgment.

Implement Deduplication

Same event might be delivered multiple times due to retries. Use event_id to detect and ignore duplicates.

Handle Failures Gracefully

Implement error handling and logging. Have fallback strategies when processing fails.

Secure Endpoints

Always verify signatures. Use HTTPS. Implement rate limiting. Don't publish URLs publicly.

Document Integrations

Document what webhooks you've configured, what each does, and how to troubleshoot.

Troubleshooting

Webhooks Not Receiving Events

Verify URL configured correctly, confirm endpoint publicly accessible, check events actually occurring, review filter settings.

Signature Verification Failures

Verify secret matches between Ayra and endpoint code, confirm computing from exact request body, check hashing algorithm.

Timeout Issues

Optimize endpoint code, move heavy processing to background jobs, increase server resources.

Duplicate Event Processing

Implement idempotency using event_id, track processed IDs in database, return success for already-processed events.

Ready to transform your agency?

Start building with Ayra today. No credit card required.