Call Created

Event name

call.created

When it fires

Sent for outbound call creation, retries, and inbound call creation paths when webhook_url exists.

Payload example

{
  "event": "call.created",
  "created_at": "2026-05-29T12:00:00Z",
  "call": {
    "id": "call_123",
    "customer_id": "cust_123",
    "application_id": "app_123",
    "provider_call_id": "uuid",
    "status": "in_progress",
    "direction": "outbound",
    "from": "+15551230001",
    "to": "+15551230002",
    "route_mode": "webhook",
    "routing_target": "app_123"
  },
  "variables": {},
  "data": {
    "event_key": "call_123:call.created"
  }
}

Important Fields

Field	Why it matters
event	Use this to route the payload to the correct handler.
created_at	UTC timestamp for ordering events in your application.
call.id	Primary key for correlating API responses, call actions, recordings, AI results, and billing records.
call.status	Current call state when the event was generated.
variables	Call variables available to your workflow, when set by earlier actions or routing logic.
data	Event-specific fields, such as gathered digits or delivery metadata.

Signature behavior

Uses X-MiniVoice-Timestamp and X-MiniVoice-Signature only when webhook_secret is configured.

Retry Behavior

MiniVoice retries webhook deliveries when your endpoint returns a non-2xx response or cannot be reached. Your receiver should be idempotent: store events by call ID and event name, then return a success response after the event is safely accepted. Process slower CRM, ticketing, or analytics work after the response whenever possible.

Failure behavior

Non-2xx responses or network errors cause retries. Your endpoint should be idempotent.

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.

Receiver checklist

Your webhook endpoint should accept the request quickly, verify the signature when a webhook secret is configured, persist the event by call ID, and return a success response after the event is stored. Process slower business tasks after the response so retries are driven by delivery state rather than CRM latency.

During testing, compare the event name, call status, timestamp, and variables object with the call you created. If a webhook arrives more than once, handle it as the same event for the same call instead of creating duplicate business records.

Testing Steps

1. Configure a test application with a webhook_url you control.
2. Trigger the event with a real call flow, such as an inbound IVR, outbound appointment reminder, or conference bridge test.
3. Log request headers and the full JSON body.
4. Confirm your handler stores the event by call.id and returns a 2xx response.
5. Repeat with a temporary 500 response to verify your idempotency logic handles retry delivery without creating duplicate business records.

Copy/Paste Examples

Real Request

curl -sS -X POST https://example.com/minivoice/webhooks \
  -H 'Content-Type: application/json' \
  -H 'X-MiniVoice-Event: call.completed' \
  --data @- <<'JSON'
{
  "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": {}
}
JSON

Real Response

{
  "ok": true
}

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

Use call.created to create or update the call row in your CRM as soon as MiniVoice accepts an inbound receptionist call or outbound appointment reminder.

Common Failure Case

{
  "ok": false,
  "error": "temporary webhook receiver failure"
}

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