Set Up the Webhook

Provide the Webhook URL where you want Volubile to send notifications in the Webhook Integration Settings.

Webhook Payload

Once a call is completed or failed, a POST request will be sent to your Webhook URL with the details of the call. This is identical to the endpoint Get a call.

{
   "id":"3c90c3cc-0d44-4b50-8888-8dd25736052a",
   "agentId":"3c90c3cc-0d44-4b50-8888-8dd25736052a",
   "phone":"+33612345678",
   "type":"INBOUND",
   "duration":360,
   "startTime":"2024-07-30T14:35:00Z",
   "endTime":"2024-07-30T14:41:00Z",
   "anonymous":false,
   "status":"COMPLETED",
   "extractors":[
      {
         "name":"customer",
         "value":[
            {
               "name":"firstname",
               "value":[
                  "John"
               ]
            },
            {
               "name":"lastname",
               "value":[
                  "Doe"
               ]
            },
            {
               "name":"address",
               "value":[
                  "123 Main St"
               ]
            }
         ]
      },
      {
         "name":"example",
         "value":[
            "example1",
            "example2"
         ]
      }
   ],
   "extractorData":{
      "customer":{
         "firstname":"John",
         "lastname":"Doe",
         "address":"123 Main St"
      },
      "example":"example1"
   },
   "classifiers":[
      {
         "name":"Customer's request",
         "value":"Refund",
         "type":"PRIMARY"
      },
      {
         "name":"Sentiment",
         "value":"Positive",
         "type":"SECONDARY"
      }
   ],
   "classifierData":{
      "Customer's request":"Refund",
      "Sentiment":"Positive"
   },
   "context":{
      "firstName":"firstname",
      "lastName":"lastname",
      "commandNumber":"5HZ99FRT",
      "system.phone":"+33612345678"
   },
   "recorded":true,
   "summary":"Discussed project requirements and next steps.",
   "created":"2024-07-30T14:45:00Z"
}

Secure the Webhook

You can choose to enable security for webhooks by generating a secret in the Webhook Integration Settings.

When enabled, we will include an X-Webhook-Signature in the request headers to your Webhook URL, allowing you to verify that the payload comes from Volubile.

Here is an example code demonstrating how to verify the HMAC signature:

import org.apache.commons.codec.binary.Hex;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import static java.nio.charset.StandardCharsets.UTF_8;
...

final var SECRET_KEY = "{volubile - webhook - secret}";

final var payload = """
{
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "agentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "type": "INBOUND",
    ...
}
""";

try {
final var mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(SECRET_KEY.getBytes(UTF_8), "HmacSHA256"));
final byte[] rawHmac = mac.doFinal(payload.getBytes());
final byte[] hexBytes = new Hex().encode(rawHmac);

final var signature = new String(hexBytes, UTF_8);
...
} catch (final NoSuchAlgorithmException | InvalidKeyException e) {
logger.error("Error occurred!");
}