Skip to main content

Overview

Context​

This document is designed to help you integrate with myKaarma webhooks. myKaarma will publish events on any change happening to the corresponding entity in our system. The third party API partners can build an API path (as in example shown later in this document). This API endpoint will be hit anytime myKaarma produces these events.

API partners can take a look at the events shape that is explained in this document and then filter and use the events according to their use cases.

Shape of API and Events​

API Path​

This API path is what we expect from the third party to provide us so the events can be sent to the API URL as a POST endpoint with a JSON request body.

https://<third-party-base-url>/<webhook-event-path>

Example: https://mykaarma-partner.ai/mykaarmaevents

Important Note on Content-type​

Please note that we will send a valid JSON, but with text/plain as Content-type in header. Please make sure that text/plain is accepted on the third party endpoint.

IP Whitelisting for receiving webhook events​

You'll need to whitelist the IP 54.174.160.138 to allow traffic from us to your webhook endpoint.

Retry Policy of Events​

The endpoint should respond with a 2xx in 5 seconds on receiving the event, otherwise, it is deemed as an invocation failure. In case of any failure, the event is retried 5 times with an exponential back off and jitter, or randomized delay.

Event Envelope​

Every myKaarma webhook event — regardless of type — shares the same outer envelope.

Headers​

AttributeExample value
content-typetext/plain
mykaarma-signature-tokensha256=xxxxxxxxxxxx
x-authorization-tokenmyKaarma_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Please check details on how to use the mykaarma-signature-token in this page.

Body Fields​

Common fields present on every webhook event regardless of type.

id
uuid
timestamp
unix ms
dealeruuid
string
departmentuuid
string
type
enum
payload
json
{
  "id": "6c7e57fe-0e06-4fc9-8120-e1593257f1cf",
  "timestamp": 1728542293678,
  "dealeruuid": "cb731d36fd635ddd6ef8dd43500892b0c0249d1c01a46dbcc445a809c0a8e3b2",
  "departmentuuid": "8ec821aefe98664ab15df7c426c3c46f9c37d0b1aeda9ff58df3db89bb0a55a3",
  "type": "customers"
}

Important Notes About Payload Format​

  1. Stringified JSON Payload: In the actual webhook events, the payload field will be an escaped stringified JSON (not a JSON object). For example, it would look like:

    "{\"customerWithVehicles\":{\"customer\":{\"id\":null,\"customerKey\":null,\"firstName\":\"myKaarma\"...

    The examples on each event page show the payload as formatted JSON objects for readability, but you will need to parse the stringified payload in your webhook endpoint.

  2. Out-of-order events: Please use the timestamp field to handle out-of-order events. Depending on your use-case you might need to use the corresponding GET API endpoint for fetching the latest state of the object received in the event.

Event Types​

There are four event types. Select one to see its full field reference and example payload:

FAQ​

What if the partner needs more information than what is given in the event such as detailed customer info?​

Third-party partners will have to call myKaarma's APIs post receiving events for further information, if needed.