Skip to main content

Webhooks

Webhooks are a powerful tool for real-time communication between your application and Kaunt's platform. By integrating webhooks into your system, you can receive instant updates about important events, such as the completion of proposal processing. This section outlines the process for setting up and handling webhooks.

Managing Webhooks​

To manage and configure your webhooks, you can utilize the Kaunt Partner Portal, which is accessible at partner.kaunt.com. The portal allows you to set up, modify, and delete webhooks associated with your account. You can specify the webhook URL at either the partner or tenant level to meet your specific needs.

Handling Webhook Notifications​

To receive webhook notifications, you need to implement an endpoint in your application that can handle the incoming POST requests from Kaunt's system. An example of the payload provided in the POST request is shown below:

{
  "Id": "2125d21e-49a3-44fe-bc2e-a74e4fbba446",
  "Url": "https://api.kaunt.com/v1/tenants/a9f76627-30b0-4ea4-915e-882b6f5f189e/companies/kaunt/invoicecodingproposals/2125d21e-49a3-44fe-bc2e-a74e4fbba446",
  "TenantId": "a9f76627-30b0-4ea4-915e-882b6f5f189e",
  "CompanyName": "kaunt",
  "CorrelationId": "e7f382eb-5339-45a7-ba57-64a6dd860338",
  "EventType": "InvoiceCodingProposalProcessingCompleted"
}
  • Id: The unique identifier of the proposal.
  • Url: The unique identifier of the proposal's resource location in Kaunt's API.
  • TenantId: The identifier of the tenant associated with the proposal.
  • CompanyName: The name of the company associated with the proposal.
  • EventType: The type of event that triggered the webhook notification. In this case, the event type is InvoiceCodingProposalProcessingCompleted. This event type indicates that the invoice coding proposal processing has completed and that the proposal is ready to be retrieved at the URL endpoint.
  • CorrelationId: A unique identifier regarding the request made towards the Kaunt API for the proposal.

When your client receives a POST request on the webhook endpoint with the provided payload, it indicates that proposal processing has completed. The webhook payload contains the necessary information, including the URL property, which represents the endpoint where the invoice coding proposal resource can be retrieved.

By making a GET-request to the URL endpoint in the payload recieved in the webhook response, your client can fetch the invoiceCodingProposal using the GET-request for invoiceCodingProposals.

Retry Policy​

If a webhook request fails, Kaunt's system will automatically retry the request using exponential backoff. The retries will continue until a maximum of 24 hours has passed since the initial request. This retry mechanism ensures that webhook notifications have a higher chance of being successfully delivered, even in the event of temporary issues or transient failures.

Webhook Event Types​

Kaunt webhooks can have the following event types:

  • InvoiceCodingProposalProcessingCompleted: Indicates that the invoice coding proposal is ready for retrieval.
  • InvoiceCodingProposalProcessingFailed: Indicates that an error occurred during invoice coding. The specific error type can be identified from the invoice proposal available at the URL endpoint provided in the webhook payload.
  • ModelReady: Indicates that the model is ready for providing coding proposals. Is only send for the first model.
  • DocumentAIDocumentResultReady: Document AI document has been successfully processed.
  • DocumentAIDocumentResultFailed: An error has occurred while processing a Document AI document.

Signature Verification​

The webhook payload is signed with a secret key to ensure that the payload is not tampered with during transmission. You can verify the signature by comparing the signature in the X-Signature-SHA256 header with the signature generated using the payload and the secret key.

When the webhook arrives at the endpoint, you can verify the signature by following these steps:

  1. Retrieve the secret key associated with the webhook from the Kaunt Partner Portal.
  2. Compute the SHA-256 HMAC of the payload using the secret key.
  3. Compare the computed signature with the signature provided in the X-Signature-SHA256 header.
  4. If the signatures match, the payload is valid and can be processed. If the signatures do not match, the payload should be discarded.

For more information and code-examples related to webhook signature verification, refer to the Webhook Signature Verification documentation by hookdeck.com

Best Practices for Webhooks​

To ensure your webhook integration is robust and future-proof, consider the following best practices:

  • Secure Your Webhook Endpoints: Use HTTPS to encrypt data in transit and ensure secure communication between Kaunt and your application.
  • Handle Additional Fields Gracefully: Be prepared for Kaunt to add new fields to the webhook payload. Your application should handle these additional fields without breaking.
  • Implement Retry Logic: Although Kaunt retries failed webhook deliveries, implement your own retry logic to handle temporary failures on your end.
  • Verify Payloads: Always verify the signature of incoming webhook payloads to ensure they are from Kaunt and have not been tampered with.
  • Log Webhook Events: Maintain logs of received webhook events for debugging and auditing purposes.
  • Respond Quickly: Ensure your webhook endpoint responds quickly to acknowledge receipt. Long processing times can lead to timeouts and unnecessary retries.
  • Handle Duplicate Events: Design your system to handle duplicate webhook events gracefully, as retries might result in the same event being sent multiple times.
  • Monitor and Alert: Set up monitoring and alerting for your webhook endpoints to detect and respond to failures promptly.