Webhooks

In this guide, we'll look at migration considerations when upgrading from Shopmonkey v1 to v2 and using Webhooks.

If you experience any issues after migration, please open a Support Ticket so we can resolve these issues with you.

Migration

Your Webhook configuration in v1 is automatically migrated to v2 when your shop is upgraded. We have taken considerable effort to make this transition seamless and require little to no change. However, there are a few subtle differences we discovered while doing this work that we wanted to document.

Webhook configuration for legacy webhooks are read only and cannot be edited. If you delete your existing legacy Webhook that was migrated, you must use the new Webhook v3 specification in your API endpoint. We recommend that you upgrade to the latest Webhook specification ASAP.

Compatibility changes

Webhook versions are denoted using v2 or v3. This comes from our API's version. Shopmonkey v1 uses API v2 and Shopmonkey 2.0 (eg. the replatform) uses API v3. A webhook configured in v1 is a v2 webhook and a webhook configured in 2.0 is a v3 webhook.

In the migration from v1 to v2, we have made some changes to the webhook payloads, mainly omitting fields that are either not tracked in v1 at all (eg IsDemo or HubspotId) or things that don't make sense to expose to our API users (eg, user notification configuration). The general shape of the payload should be similar enough such that our customers who migrate from v1 to v2 will not need to make any changes to their webhook consumers. However, some of these changes are made by a best guess while trying to balance compatibility and may not be perfect.

Changes

The following are the differences between the different Events:

Order

The following fields were excluded because they were tracked elsewhere or not at all in v2:

  • includeAppointmentsOnOrderPDF
  • includeAuthorizationsOnOrderPDF
  • includeEpaOnLabor
  • includeEpaOnParts
  • includeMessagesOnOrderPDF
  • isLaborShopSupplies
  • isLaborTaxable
  • isPartShopSupplies
  • isShopSuppliesTaxable
  • isWorkOrderWithAppointments
  • isWorkOrderWithHours
  • isWorkOrderWithInternalNotes
  • isWorkOrderWithPricing
  • laborCommission
  • lastViewedDate
  • noteDate
  • partCommission
  • partsTechSessionId
  • qbInvoiceNumber
  • quickbooks
  • shopSuppliesMaxCap
  • shopSuppliesValueType
  • shouldTrackQBDepartment
  • tireCommission
  • totalsFormulaVersion
  • useGstPstHst

User

The following fields have been removed from the user object because represent user permissions which have been moved to Roles in v2:

  • isAllowedAllTimeClocks
  • isAllowedCalendar
  • isAllowedCannedJobs
  • isAllowedChangeLaborStatus
  • isAllowedCompanySettings
  • isAllowedCompanySwitching
  • isAllowedDashboard
  • isAllowedEditAuthorizedOrders
  • isAllowedEditInvoices
  • isAllowedEditTimesheetEntries
  • isAllowedEditUsers
  • isAllowedInspections
  • isAllowedInventory
  • isAllowedInventoryCategories
  • isAllowedLists
  • isAllowedManualTimesheets
  • isAllowedMessagingCustomers
  • isAllowedNotifyChangeAppointmentStatus
  • isAllowedNotifyCustomerMakesPayment
  • isAllowedNotifyCustomerSendsMessage
  • isAllowedNotifyInternalNotePosted
  • isAllowedNotifyJobAssigned
  • isAllowedNotifyLaborStatusChanged
  • isAllowedNotifyOrderAuthorized
  • isAllowedNotifyQBInventoryAutoSyncUpdates
  • isAllowedNotifyTeammateSendsMessage
  • isAllowedNotifyTechRecommendationApproved
  • isAllowedNotifyWorkRequestReceived
  • isAllowedPricingMatrices
  • isAllowedProfitability
  • isAllowedReportCenter
  • isAllowedTimeclock
  • isAllowedTimeclockMobileAccess
  • isAllowedTimeclockWebAccess
  • isAllowedTimesheets
  • isAllowedViewAllOrders
  • isAllowedViewEveryonesCalendar
  • isAllowedWorkflow
  • inventoryAccessLevel
  • orderView
  • adminAllowedToWriteInCompanies
  • shouldTrackTimeclockLocation

The following fields have been removed from the user object because their use-case is not clear and implementing them would slow down the webhook processing:

  • notifyChangeAppointmentStatus
  • notifyCustomerMakesPayment
  • notifyCustomerSendsMessage
  • notifyInternalNotePosted
  • notifyJobAssigned
  • notifyLaborStatusChanged
  • notifyOrderAuthorized
  • notifyQBInventoryAutoSyncUpdates
  • notifyTeammateSendsMessage
  • notifyTechRecommendationApproved
  • notifyWorkRequestReceived
  • hasEnabledSMSNotifications
  • orderPageTabsOrder

Other:

  • hubspotId was removed because not tracked in v2
  • isDemo remains but will always be false in v2
  • isArchived remains but will always be false in v2
  • isIncludedToCalendar remains but will always be true in v2
  • activeWorkflow removed because not tracked in v2
  • requestPasswordResetCode, confirmationCode and confirmed are removed because not tracked in v2

Payment

The following fields have been impacted:

  • firstMileData remains but is always null, v2 does not use firstmile
  • stripeData remains but is always null because it is not tracked this way in v2
  • isDemo remains but will always be false in v2

Inventory Part

The following fields have been impacted:

  • shouldSyncToQB was removed because its tracked in a different record

Purchase Order

The following fields have been impacted:

  • isDemo remains but will always be false in v2
  • mappings.items.inventoryCount was removed because it it would be expensive to query
  • purchaseOrderPdfUrl was removed because it is generated on the fly in v2

Vehicle

The following fields have been impacted:

  • isDemo remains but will always be false in v2
  • initialStandardCarData, standardCarData, and additionalCarData are removed because they are not tracked in v2
  • motors is removed

Message

The following fields have been impacted:

  • isDemo remains but will always be false in v2
  • files was removed because they are difficult to include securely
  • publicId was removed because it is not tracked in v2