myKaarma Webhook Events
Context
This document is designed to help you integrate with myKaarma webhooks. myKaarma will publish customer, appointment and order 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
Shape of myKaarma Event
Body
This table explains the different attributes associated with events in myKaarma.
| Attribute | Description |
|---|---|
| Source | The source where this event generated. This can take values - mykaarma.scheduler, mykaarma.customer, mykaarma.orders. |
| id | Unique event ID. Can be used along with eventType for deduplication. |
| dataType | Can be service-orders, appointments, or customers. |
| timestamp | Time of the event occurrence (UTC). Used to handle out-of-order events. |
| eventType | pointInTime for this context. |
| dealeruuid | Unique 64-character identifier for the dealer. |
| departmentuuid | Unique 64-character identifier for the department. |
| payload | Stringified JSON corresponding to the event type. |
| x-authorization-token | This HTTP request header will be shared beforehand for verification. |
Note
These fields will be common to all the myKaarma events with the payload differing according to the events.
Example:
{
"id": "6c7e57fe-0e06-4fc9-8120-e1593257f1cf",
"timestamp": 1728542293678,
"dealeruuid": "_dealeruuid",
"departmentuuid": "_departmentuuid",
"dataType": "service-orders/appointments/customers",
"eventType": "pointintime",
"payload": { ... }
}
There will be three different kinds of events
- Customer event
- Appointment event
- Order event
Example Customer Payload Event
The payload will include the model of the Customer that third-party partners already receive from calling the myKaarma Customer API You can find the documentation references for the fields received in customerWithVehicles payload here.
Note: The actual payload below would be an escaped stringified JSON and would look something like:
"{\"customerWithVehicles\":{\"customer\":{\"id\":null,\"customerKey\":\"testKey123\",\"firstName\":\"John\",\"middleName\":\"\",\"lastName\":\"Doe\"...
Important Notes
- The architecture for customer creation and update pushes events via an indexer job, which runs once per second.
- If a particular customer has been updated multiple times within a duration of less than 1 second, you will receive only a single update event with the final customer data.
Example Payload
{
"id": "569841a7-230d-41ec-9e64-26839cda986e",
"timestamp": 1731484042215,
"dealeruuid": "5765507a95f23d2da7c96b5d88100bfebdc2883af8cb925ce2b61934884b24b5",
"departmentuuid": "f05f0d7a90c09cd48b8398addd477c8f2acf2dee8bae7b013ee2693e651c62b4",
"dataType": "customers",
"eventType": "pointintime",
"payload": '{
"customerWithVehicles": {
"customer": {
"id": null,
"customerKey":testKey123,
"firstName": "John",
"middleName": "",
"lastName": "Doe",
"company": null,
"preferredLocale": "en-us",
"emails": [
{
"emailAddress": "test.mkLeiferst@gmail.com",
"label": "home",
"okToEmail": true,
"isPreferred": true,
"comments": null
}
],
"phoneNumbers": [
{
"phoneNumber": "+13108170196",
"label": "cell",
"okToCall": true,
"okToText": true,
"isPreferred": true,
"comments": null
}
],
"preferredCommunication": null,
"bestTimeToContact": {
"startTime": null,
"endTime": null
},
"addresses": [
{
"line1": "100 W Broadway",
"line2": "",
"city": "Long Beach",
"zip": null,
"addressType": "P",
"type": "PRIMARY",
"country": "United States",
"updateTS": 1731483922000,
"uuid": "FgkuPqGHIR8PgTMlHj8fUylxb_eA48p8oBtz9AqGFig",
"isValid": true,
"isPreferred": false,
"state": "CA"
}
],
"availability": 0,
"isBusiness": false,
"customerUuid": "NjBuU_4VccfPr_hgA3s25QVzcJ0kzTMwZsCFYusRns4",
"customerId": "NjBuU_4VccfPr_hgA3s25QVzcJ0kzTMwZsCFYusRns4"
},
"vehicles": [
{
"id": null,
"vin": null,
"vehicleKey": "Key0MUBTXOUH3",
"isValid": false,
"imageUrl": null,
"brandId": null,
"licensePlate": null,
"color": null,
"vehicleModel": "1 Series M",
"vehicleYear": "2011",
"vehicleTrim": "Base",
"vehicleUuid": "vNzot7pDZgj3DKETdBWrcB0RFF4sQiCVyjul78vuNH0",
"vehicleEngine": null,
"estimatedMileage": null,
"vehicleMake": "BMW"
}
]
}
}'
}
caution
For now, please ignore appointment and order events.
Appointment Event
The appointment event will be fired every time an appointment is created, updated or deleted in myKaarma. You can use event and newStatus fields to identify what caused this event to trigger. You can filter these events depending on your use case and ignore the ones irrelevant to you.
These events have everything that you get on hitting our get APIs and more. Let us walk through what the payload of these events would look like:
| Attribute | Description |
|---|---|
| uuid | Unique identifier of the event in myKaarma. |
| departmentUuid | Unique identifier of the dealer department for which the appointment is scheduled. |
| subscriberName | Name of the service subscriber or the user of our APIs that triggered the event. |
| serviceAppointmentRequestLoanerBookingList | This is a list to show all the loaner bookings that have been done for this appointment. This usually contains information like booking ID, time, etc., when booking loaners through third parties like TSD, Logitrac, etc. |
| event | This field basically tells you what triggered this appointment event. For the complete list of these types of events, please check the table below. |
| appointmentInfoResponse | This is the data model that you receive from myKaarma when getting appointments. Please refer to this page. for details. |
This table explains the different values 'event' field in these events can take:
| 'event' Field Value | Meaning |
|---|---|
| CREATED | The appointment has been created. |
| UPDATED | Some parameter (other than date or time) in the appointment has been changed. |
| CANCELLED | The appointment has been cancelled. |
| PUSHED_DMS | The appointment has been pushed to the data management system (DMS) that the dealership uses. |
| REMINDER_TEXT_SENT | A reminder text has been sent to the customer. |
| REMINDER_EMAIL_SENT | A reminder email has been sent to the customer. |
| DEALERORDER_MAPPED | A repair order has been mapped to the appointment. This signifies that the customer showed up for the appointment. |
| DEALERORDER_UNMAPPED | A repair order has been unmapped from the appointment. This means an incorrect order was mapped and has now been corrected. This can happen when a repair order was mapped based on probable matching (e.g., name, phone number), but a more certain mapping (UUID-based) replaces it. |
| LOANER_BOOKED | A loaner has been booked for the customer related to this appointment. |
| LOANER_CANCELLED | The loaner that was booked for the customer has been cancelled. |
| LOANER_UPDATED | There has been some change in the loaner booking that was made earlier. |
| LOANER_BOOKING_FAILURE | There has been a failure in the loaner booking system when trying to book a loaner for the customer. |
| LOANER_UPDATE_FAILURE | There has been a failure in the loaner booking system when trying to update the loaner booking for the customer. |
| LOANER_CANCEL_FAILURE | There has been a failure in the loaner booking system when trying to cancel the loaner booking for the customer. |
| PUSHED_DMS_FAILURE | There has been a failure when trying to push the appointment to the dealership's data management system (DMS). |
| RESCHEDULED | The appointment has been rescheduled to a different time or date. |
| SHOW_WITHOUT_RO | The appointment has been marked as "show" manually by the service advisor without a repair order (RO) being attached. Some users at the dealership have the authority to do this through myKaarma UI. |
Note:
An event with 'event' field as
"UPDATED"and 'newStatus' as"No Show"would mean the customer didn't show up for the appointment.- Please note: This appointment can still be marked as Show later by the advisor. The event will come with 'event' field as
"DEALERORDER_MAPPED"and 'newStatus' as"Show".
- Please note: This appointment can still be marked as Show later by the advisor. The event will come with 'event' field as
An event with 'event' field as
"DEALERORDER_MAPPED"and 'newStatus' as"Show"would mean the customer has shown up for the appointment.- Please note: This appointment can still be marked as No Show later by the advisor. The event will come with 'event' field as
"DEALERORDER_UNMAPPED"and 'newStatus' as"No Show". This event is not published right now, we are working on publishing this.
- Please note: This appointment can still be marked as No Show later by the advisor. The event will come with 'event' field as
Important Note
- For a single appointment update from myKaarma, you will receive two appointment events over the webhook.
- This happens because every time an appointment is created/updated from myKaarma, the latest details are pushed to DMS, prompting DMS to send another update event, which triggers the second event over the webhook.
- When an appointment is created from myKaarma, you will receive a SCHEDULED event (due to myKaarma creation) and an UPDATED event (due to the DMS update), for example, when an appointment key is provided by DMS.
caution
For now, please ignore order events.
Example Order Payload Event
The payload will include the model of the Order Info that third-party partners already receive from calling the myKaarma Order API.
You can find the documentation references for the fields received under order key of the payload here.
Note: The actual payload below would be an escaped stringified JSON and would look something like:
{"uuid":"ALO6GAyJsjHWKR7rMBxD5lrVWof5K1oMcAPqCnz1GIyx","order":{"type":"RO","header":{"orderNumber":"A85483C","serviceAccount":"KR4CERT-S","accountingAccount":"KR4CERT-A","dmsStatus":"O","status":"O","deptType":"KR4CERT-S",...}
Example Payload
{
"id": "06b8934b-5cd6-4576-bb70-424646e9ad00",
"timestamp": 1731482869488,
"dealeruuid": "5765507a95f23d2da7c96b5d88100bfebdc2883af8cb925ce2b61934884b24b5",
"departmentuuid": "f05f0d7a90c09cd48b8398addd477c8f2acf2dee8bae7b013ee2693e651c62b4",
"dataType": "service-orders",
"eventType": "pointintime",
"payload": '{
"uuid": "ALO6GAyJsjHWKR7rMBxD5lrVWof5K1oMcAPqCnz1GIyx",
"order": {
"type": "RO",
"header": {
"orderNumber": "A85483C",
"serviceAccount": "KR4CERT-S",
"accountingAccount": "KR4CERT-A",
"dmsStatus": "O",
"status": "O",
"deptType": "KR4CERT-S",
"advisorNumber": "qa_automation",
"advisorName": "",
"dealerAssociateUuid": "2c2407de46d137c17442208b8a7359d9b0ef9abd3ea6e0e33f5bca667a3d1c7a",
"originalAssociateUUID": "2c2407de46d137c17442208b8a7359d9b0ef9abd3ea6e0e33f5bca667a3d1c7a",
"appointmentNumber": "",
"tagNumber": "T205",
"mileageIn": "75000",
"mileageOut": "75000",
"orderDate": "2024-11-12",
"orderTime": "00:00:00",
"promisedDate": "2017-05-05",
"promisedTime": "21:00:00",
"voidDate": "",
"closeDate": "2024-11-12",
"closeTime": "",
"waiter": "N",
"rental": "",
"soldHours": "1.10",
"actualHours": "1.00",
"laborCost": "4.00",
"laborSale": "82.00",
"laborSaleCustomer": "82.00",
"laborSaleInternal": "0.00",
"laborSaleWarranty": "0.00",
"partsCost": "5.00",
"partsCostCustomer": "5.00",
"partsCostInternal": "0.00",
"partsCostWarranty": "0.00",
"partsSale": "0.00",
"partsSaleCustomer": "20.00",
"partsSaleInternal": "0.00",
"partsSaleWarranty": "0.00",
"lubeSale": "",
"lubeSaleCustomer": "0.00",
"lubeSaleInternal": "0.00",
"lubeSaleWarranty": "0.00",
"miscSale": "5.00",
"miscSaleCustomer": "5.00",
"miscSaleInternal": "3.00",
"miscSaleWarranty": "4.00",
"subletSale": "",
"subletSaleCustomer": "5.00",
"subletSaleInternal": "0.00",
"subletSaleWarranty": "0.00",
"customerPayAmount": "16.00",
"customerPayStateTax": "1.84",
"warrantyPayStateTax": "",
"internalPayStateTax": "",
"internalPayAmount": "0.00",
"warrantyPayAmount": "0.00",
"invoiceURL": null,
"payTypes": "C--",
"description": null,
"printDate": null,
"printTime": null,
"deliveryAmount": null,
"estimate": "",
"localTaxAmountCustomer": "",
"localTaxAmountWarranty": "",
"localTaxAmountInternal": "",
"stockNumber": null,
"isInternal": false,
"isVoided": null,
"invoiceTotal": null
},
"vehicle": {
"uuid": "D25m1pBLieewXSlmPWQ7McGBAOOTDvaRbJMeO01FSGo",
"vin": "1M1AK06Y96N008881",
"make": "Honda",
"key": "Test-789565",
"model": "CXN613",
"color": null
},
"customer": {
"uuid": "J0sEQMXRBe_91YvAPV1HR1zMK-rlFYI8jLg1DnjCyHM",
"key": "CK165710",
"firstName": "Automation",
"lastName": "Test-789565"
},
"jobs": [
{
"jobIdentifier": "A-1",
"jobNumberString": "A",
"lopSeqNumber": "1",
"laborOpCode": "02",
"laborOpCodeDesc": "Customer declined oil filter change.",
"laborType": "C",
"dmsLaborType": "C",
"serviceType": "",
"jobTotal": "33",
"laborSale": "13.00",
"soldHours": "0.10",
"actualHours": "0.50",
"partsSale": "20.00",
"miscSale": "5.00",
"shopCharge": null,
"bookerNo": "1",
"dispatchLineStatus": "C93",
"techNos": "9999",
"campaignCode": "",
"parts": null,
"gog": [
{
"itemType": "",
"itemDescription": "",
"jobNumber": null,
"quantity": "",
"saleTotal": "",
"salePrice": "",
"laborType": ""
}
],
"techHours": [
{
"techNo": "9999",
"partSeqNo": "",
"laborCost": "4.00",
"laborSale": "13.00",
"soldHours": "0.10",
"otherHours": "",
"laborType": "C",
"actualHours": "0.50",
"lineCode": "A",
"mcdLaborPercentage": "",
"timeCardHours": ""
}
],
"comments": null,
"ccc": {
"complaint": "CHANGED OIL FILTER, LUBE CHASSIS, TOP OFF FLUIDS CK TIRE PRESS.",
"complaintCode": "02",
"cause": "L.O.F.",
"correction": ""
},
"estimates": {
"laborEstimate": null,
"partsEstimate": null,
"serviceEstimate": null,
"taxEstimate": null,
"lubeEstimate": null,
"miscEstimate": null,
"subletEstimate": null
},
"dispatchCode": "CS10",
"complaintCode": "02",
"addOnLine": "N",
"partsFlag": "1",
"dispatchEstimatedDuration": "0.5",
"comeBackFlag": "0"
},
{
"jobIdentifier": "B-2",
"jobNumberString": "B",
"lopSeqNumber": "2",
"laborOpCode": "",
"laborOpCodeDesc": "30k service.",
"laborType": "C",
"dmsLaborType": "C",
"serviceType": "",
"jobTotal": "35",
"laborSale": "15.00",
"soldHours": "1.10",
"actualHours": "1.50",
"partsSale": "20.00",
"miscSale": "5.00",
"shopCharge": null,
"bookerNo": "1",
"dispatchLineStatus": "C93",
"techNos": "9999",
"campaignCode": "",
"parts": null,
"gog": [
{
"itemType": "",
"itemDescription": "",
"jobNumber": null,
"quantity": "",
"saleTotal": "",
"salePrice": "",
"laborType": ""
}
],
"techHours": [
{
"techNo": "9999",
"partSeqNo": "",
"laborCost": "6.00",
"laborSale": "15.00",
"soldHours": "1.10",
"otherHours": "",
"laborType": "C",
"actualHours": "1.50",
"lineCode": "B",
"mcdLaborPercentage": "",
"timeCardHours": ""
}
],
"comments": null,
"ccc": {
"complaint": "30k service",
"complaintCode": "02",
"cause": "L.O.F.",
"correction": ""
},
"estimates": {
"laborEstimate": null,
"partsEstimate": null,
"serviceEstimate": null,
"taxEstimate": null,
"lubeEstimate": null,
"miscEstimate": null,
"subletEstimate": null
},
"dispatchCode": "CS10",
"complaintCode": "02",
"addOnLine": "N",
"partsFlag": "1",
"dispatchEstimatedDuration": "0.5",
"comeBackFlag": "0"
},
{
"jobIdentifier": "C-2",
"jobNumberString": "C",
"lopSeqNumber": "2",
"laborOpCode": "",
"laborOpCodeDesc": "CUSTOMER STATES OIL PRESSURE LIGHT IS ON",
"laborType": "C",
"dmsLaborType": "C",
"serviceType": "",
"jobTotal": "38",
"laborSale": "17.00",
"soldHours": "1.10",
"actualHours": "2.50",
"partsSale": "21.00",
"miscSale": "5.00",
"shopCharge": null,
"bookerNo": "1",
"dispatchLineStatus": "C93",
"techNos": "9999",
"campaignCode": "",
"parts": null,
"gog": [
{
"itemType": "",
"itemDescription": "",
"jobNumber": null,
"quantity": "",
"saleTotal": "",
"salePrice": "",
"laborType": ""
}
],
"techHours": [
{
"techNo": "9999",
"partSeqNo": "",
"laborCost": "7.00",
"laborSale": "17.00",
"soldHours": "1.10",
"otherHours": "",
"laborType": "C",
"actualHours": "2.50",
"lineCode": "C",
"mcdLaborPercentage": "",
"timeCardHours": ""
}
],
"comments": null,
"ccc": {
"complaint": "CUSTOMER STATES OIL PRESSURE LIGHT IS ON",
"complaintCode": "02",
"cause": "L.O.F.",
"correction": ""
},
"estimates": {
"laborEstimate": null,
"partsEstimate": null,
"serviceEstimate": null,
"taxEstimate": null,
"lubeEstimate": null,
"miscEstimate": null,
"subletEstimate": null
},
"dispatchCode": "CS10",
"complaintCode": "02",
"addOnLine": "N",
"partsFlag": "1",
"dispatchEstimatedDuration": "0.5",
"comeBackFlag": "0"
}
],
"mls": null
}
}'
}
caution
For now, please ignore unrelated events.
Questions
Which appointment update events will be sent to the third party?
All appointment updates for the dealers that the third party subscribes to in the context of myKaarma webhooks.
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.
Why am I receiving multiple appointment events for a single create/update?
- For a single appointment update from myKaarma, you will receive two appointment events over the webhook.
- This happens because every time an appointment is created/updated from myKaarma, the latest details are pushed to DMS, prompting DMS to send another update event, which triggers the second event over the webhook.
- When an appointment is created from myKaarma, you will receive a SCHEDULED event (due to myKaarma creation) and an UPDATED event (due to the DMS update), for example, when an appointment key is provided by DMS.
Are customer events 1:1 in terms of customer updates?
Not always, as explained in "The architecture for customer creation and update pushes events via an indexer job, which runs once per second.".