myKaarma Webhook Events
Context
Following are the details of the API path that the third-party partner will build and the shape of the events that the third-party partner can expect myKaarma to send whenever there is an update on an entity in myKaarma.
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
{
"id": "6c7e57fe-0e06-4fc9-8120-e1593257f1cf",
"timestamp": 1728542293678,
"dealeruuid": "_dealeruuid",
"departmentuuid": "_departmentuuid",
"dataType": "service-orders/appointments/customers",
"eventType": "pointintime",
"payload": { ... }
}
Attributes
- Source: Will be
mykaarma.scheduler,mykaarma.customer,mykaarma.orders - id: Unique event ID. Can be used along with
eventTypefor deduplication. - dataType: Can be
service-orders,appointments, orcustomers. - timestamp: Time of the event occurrence (UTC). Used to handle out-of-order events.
- eventType:
pointInTimefor 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.
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
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.
Example Appointment Event
The payload will include the model of the Appointment Info that third-party partners already receive from calling the myKaarma Appointment API.
Note: The actual payload below would be an escaped stringified JSON and would look something like:
{"uuid":"75b14842-52f7-4092-ad13-15162264da42","departmentUuid":"f05f0d7a90c09cd48b8398addd477c8f2acf2dee8bae7b013ee2693e651c62b4","subscriberName":"mkDealer","serviceAppointmentRequestLoanerBookingList":[],"event":"RESCHEDULED","appointmentInfoResponse":{"uuid":"486IV678JZYQoLEHFMbGTJJVQLC2tUlyH0c96TWc9AA","customerInformation":{"firstName":"Automation","lastName":"Test-349071",...}
Important Notes
- 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.
Example Payload
{
"id": "75b14842-52f7-4092-ad13-15162264da42",
"timestamp": 1731664267032,
"dealeruuid": "5765507a95f23d2da7c96b5d88100bfebdc2883af8cb925ce2b61934884b24b5",
"departmentuuid": "f05f0d7a90c09cd48b8398addd477c8f2acf2dee8bae7b013ee2693e651c62b4",
"dataType": "appointments",
"eventType": "pointintime",
"payload": '{
"uuid":"75b14842-52f7-4092-ad13-15162264da42",
"departmentUuid":"f05f0d7a90c09cd48b8398addd477c8f2acf2dee8bae7b013ee2693e651c62b4",
"subscriberName":"mkDealer",
"serviceAppointmentRequestLoanerBookingList":[
],
"event":"RESCHEDULED",
"appointmentInfoResponse":{
"uuid":"486IV678JZYQoLEHFMbGTJJVQLC2tUlyH0c96TWc9AA",
"customerInformation":{
"firstName":"Automation",
"lastName":"Test-349071",
"company":null,
"customerKey":"CK670699",
"uuid":"AP6_8l0X-OLUT1P9Tuw4Vr13JuULz6mBoi7dUiTHZh7O"
},
"vehicleInformation":{
"vin":"1GCCT14R0H2164173",
"vehicleKey":"Test-349071",
"model":"A3",
"year":"2025",
"brand":"Audi",
"trim":"Dynamic",
"engine":null,
"mileage":"75000",
"dealerUuid":null,
"uuid":"Eh_V7cnqRZsLUVF9OHvvyuKtPX6MO3Ife5ZtpOWsRzw"
},
"orderInformation":{
"uuid":null,
"orderNumber":null,
"orderDate":null,
"orderType":null
},
"dealerUuid":"5765507a95f23d2da7c96b5d88100bfebdc2883af8cb925ce2b61934884b24b5",
"assignedAdvisorUuid":"6df1dee2757815ecaf69822ad99daf3f3025f49ab0cc984e41d050412dbda8af",
"assignedAdvisorDmsDepartmentCode":null,
"creatorAdvisorUuid":"eaaddaffe690374eec399de275875bdf1b95651287f5bb42961b7e91538a6003",
"date":"2024-11-14 19:34:56",
"startTime":"2024-11-15 16:20:00",
"endTime":"2024-11-15 16:39:59",
"transportOption":{
"uuid":"Uuid",
"altTransportation":"none",
"bookingId":null,
"bookInThirdParty":false,
"bookingStartDate":null,
"bookingEndDate":null,
"bookingIsManual":null,
"bookingIsValid":null,
"transportation":"None",
"organicTransportation":"None",
"subTransportOptionUuid":null
},
"appointmentKey":null,
"mileageText":"",
"recall":false,
"appointmentSource":"dealerapp",
"status":"N",
"newStatus":"Rescheduled",
"comments":"Automation public notes for E9SC9O2EQU",
"internalNotes":"Automation internal notes for E9SC9O2EQU",
"isCancelled":null,
"reminderCount":0,
"serviceList":[
{
"uuid":"qt8eH7bNmElrEOgRMj4JcDOxaWb_gwnigU3wEG-lxy4",
"opCode":"ht0m2WN6ObE9SC9O2EQU",
"laborOpCode":"TWqVZ6ZCzPE9SC9O2EQU",
"description":"jLXm5kvsNIE9SC9O2EQU",
"operationType":"SERVICEMENU",
"laborTotal":10,
"partsTotal":10,
"shopFees":null,
"taxes":null,
"price":20.00,
"isValid":true,
"payType":"C",
"sortOrder":1,
"parentOpcodeUuid":null,
"menuUuid":"5K0-GVI8-9fHflNmxxjsihPIIyj1b721BbKmn2sGK9I",
"recallID":null,
"durationInMins":720,
"isCustomConcern":false,
"isDealerAddedLine":false
},
{
"uuid":"qt8eH7bNmElrEOgRMj4JcDOxaWb_gwnigU3wEG-lxy4",
"opCode":"ht0m2WN6ObE9SC9O2EQU",
"laborOpCode":"TWqVZ6ZCzPE9SC9O2EQU",
"description":"ht0m2WN6ObE9SC9O2EQU",
"operationType":"OPCODE",
"laborTotal":10,
"partsTotal":10,
"shopFees":null,
"taxes":null,
"price":20.00,
"isValid":true,
"payType":"CUSTOMER",
"sortOrder":2,
"parentOpcodeUuid":"qt8eH7bNmElrEOgRMj4JcDOxaWb_gwnigU3wEG-lxy4",
"menuUuid":"5K0-GVI8-9fHflNmxxjsihPIIyj1b721BbKmn2sGK9I",
"recallID":null,
"durationInMins":720,
"isCustomConcern":false,
"isDealerAddedLine":false
},
{
"uuid":"aeC1p0d9Jrfn-67dZsMGvv7hbntx2yqm0nJCLpoKwT0",
"opCode":"i43heS5e7dE9SC9O2EQU",
"laborOpCode":"i43heS5e7dE9SC9O2EQU",
"description":"i43heS5e7dE9SC9O2EQU",
"operationType":"OPCODE",
"laborTotal":10,
"partsTotal":10,
"shopFees":null,
"taxes":null,
"price":20.00,
"isValid":true,
"payType":"CUSTOMER",
"sortOrder":3,
"parentOpcodeUuid":"qt8eH7bNmElrEOgRMj4JcDOxaWb_gwnigU3wEG-lxy4",
"menuUuid":"5K0-GVI8-9fHflNmxxjsihPIIyj1b721BbKmn2sGK9I",
"recallID":null,
"durationInMins":720,
"isCustomConcern":false,
"isDealerAddedLine":false
}
],
"skillList":null,
"appointmentCommunicationPreferences":{
"emailConfirmation":true,
"textConfirmation":true,
"emailReminder":true,
"textReminder":true,
"confirmationEmail":null,
"confirmationPhoneNumber":null,
"notifyCustomer":true,
"sendCommunicationToDA":true
},
"pdrToOpcodes":{
},
"estimatePdfS3Url":null,
"customerSignatureUrl":null,
"signatureRequestId":null,
"signatureCaptureUrl":null,
"signedEstimatePdfUrl":null,
"estimateSignatureStatus":null,
"teamUuid":null,
"dispatchCode":null,
"customerVehicleInspectionId":null,
"sarCheckinDataDTO":null
},
"eventCreationDateTime":"2024-11-15 01:51:07.006",
"updatedByUserUuid":"2c2407de46d137c17442208b8a7359d9b0ef9abd3ea6e0e33f5bca667a3d1c7a"
}'
}
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.
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.".