Configure webhooks

Kravia offers a generic webhook interface. It can be configured at a creditor level in order to receive notification about invoice/case update.

Note that at the time being, it is not possible to specify which message to receive only for which creditor to activate as the webhook is simple notification hub

Configure a webhook url Copied!

It is possible to configure an HTTP webhook on a creditor using the following API endpoint

curl 'https://api.kravia.ai/api/v2/creditor/{id}/webhook' \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
  "secret": "SOME_SECRET",
  "enabled": true,
  "url": "https://some-public-url/webhook
}'

All changes on invoices owned by this creditor will then trigger a standard API call to the configured API endpoint and the payload of the HTTP request will be signed with the provided secret value which can be unique per creditor.

Note: the provided http url must be public and should not require any authentication.

Webhook formatCopied!

Kravia provides a generic webhook format that requires:

A public POST https endpoint
A shared secret

The payload of the webhook is generic and contains the following information:

{
    "header": {
        "algorithm": "MD5"
    },
    "data": {
        "timestamp": 1663063069,
        "eventType": "CaseUpdate",
        "claimId": 123443
    },
    "signature": "16a05d8c9d625d70b856aa174144220f"
}

Since the webhook url needs to be a public POST endpoint, partners can not build any authorization. As a security measure, the webhook payload will not contain any sensitive information and it will contain a signature that is generated using the shared secret. This allows partner to verify the authenticity of the webhook.

Below is a code snippet to validate the webhook payment signature

public static bool ValidateSignature(WebhookEvent webhookEvent, string secret) 
{
   var data = JsonConvert.SerializeObject(webhookEvent.Data);
   var signature = DigestHelper.GenerateDigest("KRAVIA", data, "", secret);

   if (signature.Equals(webhookEvent.Signature))
      return true;

   return false;
}

public class DigestHelper
{
    public static string GenerateDigest(string realm, string data, string nounce, string secret)
    {
       var message = $"{data}:{realm}:{nounce}:{secret}";

       using (var md5 = MD5.Create())
       {
           var inputBytes = Encoding.ASCII.GetBytes(message);
           var hash = md5.ComputeHash(inputBytes);
           var result = BitConverter.ToString(hash);
           return result.Replace("-", string.Empty).ToLower();
       }
    }
}