What's the difference between webhook v1 and v2?

This document explains the differences between v1 and v2 of the Leadsie webhook payload format.

Summary

The webhook data is sent each time a new connection is made, whether successful or unsuccessful, and includes details of what your client granted.

v1 provides basic connection status information with a success/failure indicator. It includes asset details like name, type, connection status, and platform-specific fields.

v2 is an enhanced version that provides richer context. It includes user assignment details, access levels, permission information, asset links, and timestamps. v2 removes some deprecated fields (like `isSuccess` and `message`) in favor of more structured data. Asset types are displayed as human-readable labels with platform context. You can now refresh assets in Leadsie to check for changes in connection status, as well as offboard them; the v2 data gives clearer information about the current status of assets, not just at the time of granting.

Technical Details

Connection Level Changes - Fields Added in v2

apiVersion field added to identify the API version
connectionSummaryText (string) - a pre-formatted summary of the connection, suitable for text output such as Slack messages
connectionSummaryHtml (string) - a pre-formatted summary of the connection, suitable for HTML output such as email
assetSummaryText (string) - a pre-formatted summary of the asset details, suitable for text output such as Slack messages (same as connectionSummaryText but only includes the list of assets on the connection)
assetSummaryHtml (string) - a pre-formatted summary of the asset details, suitable for HTML output such as email (same as connectionSummaryHtml but only includes the list of assets on the connection)
assetCount (number) - how many assets are included on the connection

Asset Level Changes - Fields Removed in v2

isSuccess (boolean) - use `connectionStatus` instead
message (string) - raw error message; this is often not very helpful, and has been replaced by notes , to give clearer explanations of any problems
inviteSentTo (string) - replaced by `connectedAccount`; see also the `wasInvitedByEmail` flag

Asset Level Changes - Fields Added in v2

platform     (string) - which platform the asset is from ("Meta", "Google", "LinkedIn", etc.)

statusLastCheckedAt     (Date) - timestamp when the asset status was last checked

linkToAsset     (string) - deep link URL to access the asset in the relevant platform, where available

assignedUsers     (array) - list of users assigned to the asset, each with:
- id (string)
- name (string)
- role     (string)
  
  isSuccess     (boolean)
  
  connectedAccount     (object) - connected account information with:
- id (string)
- name (string)
wasInvitedByEmail (boolean) - indicates if access was granted via email invitation
wasCreatedByLeadsie (boolean) - indicates if the asset was created by the client through Leadsie
wasGrantedViaAssetType (string) - indicates if access to the asset was granted via a different asset; this may be "Facebook Page" for an Instagram account, or "Facebook Ad Account" for an Instagram account or Meta Dataset
platformPermissionsGranted (array) - list of fine-grained permissions granted for the asset (currently only supported for Facebook Pages)
accessLevel (string) - access level granted: "ViewOnly", "Manage", or "Owner"
notes (string) - any notes associated with the asset, including advice in the case of a problem granting it

Asset Level Changes - Fields Modified in v2

type (string) - the possible values of this field have been adjusted slightly for clarity

Request Level Changes

No changes - both versions expose the same fields.

Reference:

The possible values for the type field on connectionAssets are:

“Meta Ad Account” | “Facebook Page” | “Facebook Catalog” | “Meta Pixel” | “Instagram Account” | “Google Analytics Account” | “Google My Business Location” | “Google Search Console” | “Google Merchant Center” | “Google Tag Manager” | “Google Ads Account” | “TikTok Advertiser Account” | “LinkedIn Company Page” | “LinkedIn Ad Account” | “Shopify Store” | “WordPress Site” | “Squarespace Website” | “Klaviyo Account” | “YouTube Channel” | “Microsoft Ads” | “Mailchimp Account” | “Pinterest Ad Account” | “GoDaddy Account” | “HubSpot Account” | “Yelp Business Account” | “X Profile” | “X Ads” | “Snapchat Business Account”