Voice Webhooks¶

Enfonica sends webhooks via HTTP(S) POST when certain events occur.

Looking to control a call?

This page documents asynchronous event notifications — CALL_STATE_UPDATE, FAX_READY, RECORDING_READY, and TRANSCRIPTION_READY. Your server returns a 2xx status and the response body is ignored. These webhooks do not control the call.

To control a call, your server responds to a VoiceML request with a VoiceML XML document. VoiceML requests are sent to a call's handler URIs and are a separate, synchronous request/response protocol.

Specification¶

Overview¶

The body of the request is a JSON serialized object.

The request will have header Content-Type: application/json; charset=utf-8.

The request will have header X-Enfonica-Event which specifies which event occurred.

Security¶

Enfonica signs every webhook with an HMAC-SHA256 signature included in the X-Enfonica-Signature header. See Request signing for details.

Response¶

If a 2xx response is received, it is deemed that the request was handled successfully. If a redirect is received, it will be followed. Otherwise, it will be deemed that a failure has occurred and attempt:

another handler URL if multiple have been specified
retry a handler URL that has already been tried

Once all handler URLs have been attempted, an additional 8 attempts will be made with delays of 1, 2, 4, 8, 60, 1800, 3600 and 7200 seconds. If all of these attempts fail, no additional attempts will be made.

Events¶

Call State Update¶

When a call transitions to a new state, a call state update webhook will be sent to the configured URI.

The request will have X-Enfonica-Event: CALL_STATE_UPDATE.

The payload of the request will be a JSON serialized instance of the call of type enfonica.voice.v1beta1.Call.

Fax Ready¶

When a fax has been successfully received, a fax ready webhook will be sent to the configure URI.

The request will have X-Enfonica-Event: FAX_READY.

The payload of the request will be a JSON serialized instance of the fax of type [enfonica.voice.v1beta1.Fax].

The fax URI specified in the request is ephemeral and will expire in 24 hours. To retrieve the fax after this point, use the enfonica.voice.v1beta1.Faxes.GetFax RPC.

Recording Ready¶

When a recording has finished processing and is ready to access, this webhook will be sent to the URI specified:

if using <Record> action, against the RecordingReadyUri attribute.

The request will have X-Enfonica-Event: RECORDING_READY.

The payload of the request will be a JSON serialized instance of the recording of type enfonica.voice.v1beta1.Recording.

The audio URIs specified in the request are ephemeral and expire in 24 hours. To retrieve the audio after this point, use the enfonica.voice.v1beta1.Recordings.GetRecording RPC.

Transcription Ready¶

When a transcription has finished processing and is ready to access, this webhook will be sent to the URI specified:

if using <Record> action, against the TranscriptionReadyUri attribute.

The request will have X-Enfonica-Event: TRANSCRIPTION_READY.

The payload of the request will be a JSON serialized instance of the transcription of type enfonica.voice.v1beta1.Transcription.

Example payload¶

{
  "name": "projects/my-project/calls/sdfsd54g65sd4gsd89fsd56fsdf5sd/transcriptions/odnmd6sduje3dssd5s83d5sd8s35sd",
  "recording": "projects/my-project/calls/sdfsd54g65sd4gsd89fsd56fsdf5sd/recordings/ps56f38cs5dsjf45s82jmdso0r72sd",
  "state": "COMPLETED",
  "duration": "10.860s",
  "channelCount": 1,
  "createTime": "2021-06-23T03:12:55.183990Z",
  "updateTime": "2021-06-23T03:13:11.596854Z",
  "utterances": [
    {
      "channel": 0,
      "offset": "0.880s",
      "duration": "9.680s",
      "text": "Hi, this is Bob. I guess we're playing phone tag. Can you call me back. Thanks."
    }
  ]
}