# Voice Webhooks

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

!!! note "Looking to control a call?"
    This page documents **asynchronous event notifications** &mdash; `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**](voiceml/requests.md) 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](../platform/request-signing.md)
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 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

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


[enfonica.voice.v1beta1.Call]: https://github.com/enfonica/enfonicaapis/blob/master/enfonica/voice/v1beta1/calls.proto
[enfonica.voice.v1beta1.Recording]: https://github.com/enfonica/enfonicaapis/blob/master/enfonica/voice/v1beta1/recordings.proto
