Signatures

When it fires

Use this page when testing webhook delivery for events generated by real call flows. Typical triggers include an inbound receptionist call, an outbound appointment reminder, a Sales or Support IVR selection, a call-forwarding transfer, or a conference bridge call reaching a terminal state.

Payload 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": {}
}

When webhook_secret is configured, sent requests include X-MiniVoice-Timestamp and X-MiniVoice-Signature. The signature value starts with v1= followed by the hex HMAC SHA-256 digest over timestamp + "." + raw body. Without a secret, signature headers are not set.

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 signature verification to confirm webhook requests came from MiniVoice before updating customer records.

Common Failure Case

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

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

Retry Behavior

MiniVoice retries webhook deliveries when your endpoint returns a non-2xx response or cannot be reached. Build handlers to be idempotent by storing the event name, call ID, and timestamp before doing slower work such as CRM updates, ticket creation, or analytics processing.

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.