Skip to main content

Webhooks Overview

MiniVoice sends HTTPS POST requests to your application's configured webhook_url when call, gather, and recording events occur. Webhooks are asynchronous notifications: they report what happened, while API requests and answer_url responses control the call.

HTTP arrival order is not guaranteed. Each new webhook event has a stable event ID and, for current events, a per-call sequence number so your application can deduplicate deliveries and reconstruct event-generation order.

Integration flow​

  1. Configure an Application webhook URL and webhook signing secret.
  2. Expose a valid public destination. HTTPS is required unless insecure HTTP has been explicitly enabled for the Application.
  3. Receive the exact raw request body and verify its signature.
  4. Deduplicate the event by its top-level id.
  5. Parse the JSON and route it using type.
  6. Persist the event, return a 2xx response quickly, and perform slower work asynchronously.

Canonical event​

{
  "id": "evt_20260901T173552.838849267_47feba5c0ce326f4",
  "type": "call.completed",
  "created_at": "2026-09-01T17:35:52.838Z",
  "sequence": 2,
  "data": {
    "call": {
      "id": "call_20260901T173513.576013050",
      "application_id": "app_20260321T130033.289233019",
      "direction": "outbound",
      "from": "+37045509630",
      "to": "+37067613663",
      "status": "completed",
      "carrier_call_id": "eb3ca595-8c80-4590-8997-310682ce0a5f"
    },
    "reason": "completed",
    "duration_seconds": 12,
    "billable_seconds": 5,
    "hangup": {
      "cause": "NORMAL_CLEARING",
      "source": "unknown",
      "sip_code": 200
    }
  }
}

See Event Structure and Reference for the complete field and event reference.

Delivery guarantees​

  • One logical event has one event id.
  • Automatic retries and manual resend preserve the event ID, type, sequence, destination, and exact stored payload.
  • Every delivery attempt has its own attempt ID.
  • MiniVoice considers any HTTP status from 200 through 299 successful.
  • Retryable failures use the documented retry policy.

Your webhook endpoint must be idempotent. Store and deduplicate webhook events by id; do not use attempt IDs for business idempotency.