Skip to main content

Webhook URL

webhook_url is an HTTPS endpoint on your server that receives MiniVoice events. Configure webhook_secret when you want signed delivery.

Your endpoint should return any 2xx status after accepting the event. Non-2xx responses are retried according to MiniVoice webhook retry behavior.

Integration guidance

Use this page as part of a complete MiniVoice integration, not as an isolated reference. Start by wiring the smallest possible version in a test application, then add business logic after you can reproduce the behaviour reliably. Keep the MiniVoice call ID in your own records, because that ID is the easiest way to connect API responses, webhook events, recordings, AI results, and billing details.

When you build the workflow, separate caller experience from backend processing. The caller should hear short prompts and reach a destination quickly. Longer work, such as updating a CRM or creating a support ticket, should happen after your webhook endpoint has accepted the event. This keeps the voice flow responsive and makes retry handling easier.

For manual testing, use one known DID, one known destination number, and one webhook receiver where you can inspect request headers and bodies. Run the same test at least three times: one normal path, one invalid input path, and one timeout or no-answer path. Save the examples that worked as fixtures for future regression tests.

Integration checklist

An application connects your API key, answer_url, webhook_url, and routing choices. Start with one test application and one simple answer_url that returns a single action. After that works, add gather, transfer, recording, or AI processing in small steps.

Before using the application for real traffic, confirm that the answer_url returns valid JSON quickly, the webhook_url accepts signed events, and the DID or trunk route points to the correct application. Keep separate applications for testing and production so experiments do not affect live callers.

Copy/Paste Examples​

Real Request​

curl -sS https://api.minivoice.eu/v1/applications \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY'

Real Response​

{
  "data": [
    {
      "id": "app_123",
      "name": "Support IVR",
      "customer_id": "cust_123",
      "answer_url": "https://example.com/answer",
      "webhook_url": "https://example.com/webhooks",
      "created_at": "2026-05-29T12:00:00Z"
    }
  ],
  "count": 1
}

Real Webhook Example​

{
  "event": "call.completed",
  "created_at": "2026-05-29T12:10:00Z",
  "call": {
    "id": "call_123",
    "customer_id": "cust_123",
    "application_id": "app_123",
    "status": "completed",
    "direction": "inbound",
    "from": "+15551230001",
    "to": "+15551230002"
  },
  "variables": {},
  "data": {}
}

Common Use Case​

Configure the application that powers a receptionist IVR, sales routing menu, or appointment reminder line.

Common Failure Case​

{
  "error": {
    "code": "invalid_request",
    "message": "answer_url must be a valid URL"
  }
}

Use the error code for branching and log the full response body while testing.