Voice Webhooks¶

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

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¶

To verify the authenticity of requests to your endpoint, Enfonica includes the header X-Enfonica-Signature. You can use the value of this header to verify that requests are originated by Enfonica.

To calculate the signature:

Get the full original URL of the request, including query parameters.
Append the value of the header X-Enfonica-Event.
Append the JSON payload (original request body).
Sign the resulting string with HMAC-SHA256 using your Enfonica signing key as the key.
Base64 encode the resulting hash code byte array.
Compare the hash to the value of X-Enfonica-Signature. If it matches, then the requests genuinely came from Enfonica.

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."
    }
  ]
}