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 Allowlisting for receiving webhook events​

myKaarma delivers webhook events through Amazon EventBridge, which sends requests from AWS's shared us-east-1 IP address pool. These addresses are not fixed and can change at any time, so there is no static IP to allowlist. Do not restrict your webhook endpoint by source IP, or events may be blocked.

To make sure a request came from myKaarma, verify the mykaarma-signature-token and x-authorization-token headers described in Headers, and optionally configure one of the authentication methods below.

Supported Authentication​

myKaarma can authenticate to your webhook endpoint using one of the following methods. Share the method and its credentials with us when your webhook is set up.

MethodCredentials we need from youHow we authenticate
BasicUsername and passwordSends an Authorization: Basic <base64(username:password)> header with every event.
Bearer tokenA static tokenSends an Authorization: Bearer <token> header with every event.
OAuth 2.0 client credentialsClient ID, client secret, your token URL, and the HTTP method (GET, POST or PUT) the token URL expects. Optional extra header, query string or body parameters for the token request.Requests an access token from your token URL and sends it in the Authorization header with every event.

In addition to the method above, every event carries the mykaarma-signature-token and x-authorization-token headers described in Headers, which you can use to verify that the request came from myKaarma.

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
stringnullable
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.

Handling the Webhook​

// express.raw() preserves the unmodified bytes needed for signature verification.
// See "Signature Token Verification" for the verifySignature implementation.

// Out-of-order handling: a lower timestamp means an older event. Ignore it if a newer event
// for the same entity was already applied. entityKey() returns the UUID of the entity in the
// payload (e.g. the customerUuid for 'customers'). In production keep this state in a shared
// store (Redis/DB) with an atomic compare-and-set; an in-memory Map is for illustration only.
// This early check only drops events that arrive late. Processing below is asynchronous, so a slow
// older event can still finish after a newer one: also guard the final write in your handler
// (e.g. UPDATE ... WHERE last_event_ts <= :timestamp) so older data never overwrites newer data.
const lastApplied = new Map();
// Entity UUID per event type, from the payload field documented on each event page. Types not
// listed return null and skip the ordering check (e.g. orders, whose top-level uuid
// identifies the event, not the entity — use the entity identifier from their page instead).
function entityKey(type, payload) {
  switch (type) {
    case 'customers': return payload.customerWithVehicles?.customer?.customerUuid;
    case 'appointments': return payload.appointmentInfoResponse?.uuid;
    case 'messages': return payload.messageDTO?.uuid;
    case 'dealer-associates': return payload.dealerAssociateUuid;
    case 'mpis':
    case 'operations':
    case 'mobile-service-appointments': return payload.uuid;
    default: return null;
  }
}

function isLatest(type, timestamp, payload) {
  const id = entityKey(type, payload);
  if (!id) return true;
  const key = type + ':' + id;
  if (timestamp < (lastApplied.get(key) ?? 0)) return false;
  lastApplied.set(key, timestamp);
  return true;
}

app.post('/webhook', express.raw({ type: '*/*' }), (req, res) => {
  // 1. Verify signature before doing anything else
  if (!verifySignature(req.headers['mykaarma-signature-token'], req.body)) {
    return res.sendStatus(401);
  }

  // 2. Parse the outer envelope
  let event;
  try {
    event = JSON.parse(req.body.toString());
  } catch (err) {
    return res.sendStatus(400);
  }

  const { id, type, timestamp, dealeruuid: dealerUuid, payload: rawPayload } = event;

  // 3. Parse the stringified payload
  let payload;
  try {
    payload = typeof rawPayload === 'string' ? JSON.parse(rawPayload) : rawPayload;
  } catch (err) {
    console.error('Failed to parse payload for event', id);
    return res.sendStatus(400);
  }

  // 4. Skip out-of-order events — still reply 200 so myKaarma does not retry them
  if (!isLatest(type, timestamp, payload)) {
    return res.sendStatus(200);
  }

  // 5. Respond 200 immediately — myKaarma retries if it doesn't receive 2xx within 5 s
  res.sendStatus(200);

  // 6. Process asynchronously so the response is not blocked
  setImmediate(() => {
    switch (type) {
      case 'mpis':          handleMpiEvent(payload, dealerUuid);   break;
      case 'customers':     handleCustomerEvent(payload);           break;
      case 'service-orders':handleOrderEvent(payload);              break;
      case 'appointments':  handleAppointmentEvent(payload);        break;
      case 'messages':      handleMessageEvent(payload);            break;
      case 'operations':    handleOperationEvent(payload);          break;
      case 'dealer-associates': handleDealerAssociateEvent(payload); break;
      case 'mobile-service-appointments': handleMobileServiceAppointmentEvent(payload); break;
      default:
        console.warn('Unknown event type:', type);
    }
  });
});

Event Types​

There are nine 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.