Internal voice gateway

What is implemented#

AckNexa can send voice notifications (paging calls from escalation policies) to an operator-configured HTTPS gateway and accept signed, sequenced callbacks. The gateway translates this contract into the customer's CUCM, SIP or PBX operations. For these paging calls no SIP stack or CUCM connector is bundled; the bridge and site-specific call testing remain customer responsibilities.

Inbound hotline calls are a different feature: live call routing includes a ready-made CUCM gateway.

Configure the adapter#

• Set VOICE_GATEWAY_URL to the private HTTPS endpoint and VOICE_GATEWAY_TOKEN to a random bearer token of at least 32 characters; _FILE is supported.
• Configure the API and workers consistently. In Helm, enable notifications.voiceGateway and provide its URL and Secret.
• Install the private CA, allow only the required network path, and restrict the gateway's permitted dial destinations.
• Ensure organization-level voice provider settings do not override the deployment gateway unintentionally.

Outbound notification#

AckNexa POSTs a JSON Message containing ID, Channel, Destination, Title, Body, IncidentID, Severity, Service, Environment and Status. The request uses Authorization: Bearer TOKEN and Idempotency-Key: NOTIFICATION_UUID. The gateway may return its call ID in X-Request-ID.

The gateway must authenticate, validate destinations, and persist idempotency before returning 2xx. Return success only for durable acceptance. Do not redirect: redirects are not followed. A successful HTTP call is not evidence that a phone rang or a person responded.

Callback and acknowledgement#

{
  "event_id": "unique-gateway-event",
  "notification_id": "NOTIFICATION_UUID",
  "state": "answered",
  "sequence": 3,
  "digit": "1"
}

POST callbacks to /v1/voice/callback. Supported states are queued, dialing, ringing, answered, no_answer, busy, failed and completed. Only explicit digit 1 with answered invokes acknowledgement; answering alone does not ACK the incident.

Use X-AckNexa-Timestamp with an RFC3339 timestamp and X-AckNexa-Voice-Signature with the hex HMAC-SHA256 of timestamp + '.' + raw body. The HMAC key is SHA256 of the per-organization callback secret. The signature has no sha256= prefix on this voice endpoint. Clock skew must stay within five minutes.

Credential provisioning and replay#

A trusted operator provisions the callback key hash in voice_gateway_credentials for the organization. Use a separate secret from the outbound bearer token. Callback event IDs must be unique and sequence values increase per notification. Duplicate event IDs and stale sequences are handled without regressing call state; the responder must still be authorized.

Acceptance test#

1. Send a notification to a dedicated internal test extension and verify gateway idempotency under retry.
2. Observe queued/ringing/answered callbacks, then test digit 1 and verify the incident ACK and cancelled pending escalation work.
3. Exercise no-answer, busy, duplicate/stale callbacks, wrong signatures, expired timestamps and revoked responder access.
4. Record actual provider/call evidence before claiming CUCM/PBX interoperability.