On this page
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
Your server has 10 seconds to respond. A 2xx response means that your server handled the request. Enfonica follows a redirect, up to 5 times. Any other response, or no response in time, is a failure.
After a failure, Enfonica tries the next handler URL, if more than one is set. When every handler URL has failed, Enfonica tries 8 more times, after delays of 1, 2, 4, 8, 60, 1800, 3600, and 7200 seconds, and then stops. That's more than three hours in total.
Because a slow response is retried, your server can receive the same webhook more than once.
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 theRecordingReadyUriattribute.
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 theTranscriptionReadyUriattribute.
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."
}
]
}