Working with Webhooks
Webhooks are callbacks to your app that fire upon specific events, like data changing on a Location object. We strongly recommend subscribing to webhook events rather than polling the API to detect changes in the Knowledge Engine.

Webhooks are not dynamically configured via the API; for each app, you can select which types of webhook events you would like to subscribe to, and you can specify the endpoint in your app that will listen to these webhook events. You can manage webhooks for each app on the “App Settings” page of the Developer Console:

ManageWebhooks
Manage webhooks


Events for all accounts linked to your app will be sent to the webhook endpoints you configure. For example, if your app has 10 customers linked to it, and you subscribe to the Locations webhook, you will receive webhook events for all 10 customers at the same webhook endpoint. To distinguish which webhook payload is associated with which Yext account, the webhook payload includes an app-specific account ID in the meta object that matches the value returned during the customer OAuth process.
ACCOUNTID Do not use or depend on any references to accountId, as this ID is a customer-settable value that is not unique across the Yext Knowledge Engine. To learn more, see Identifying Yext Objects.


Note that for webhook events where an object is returned, the webhook payload contains the full updated object, not just the fields that have been changed. This feature allows your app to immediately act on the event without needing to call another API endpoint to retrieve the object. However, you may need to determine what data has changed in the object. For the Locations endpoint specifically, the meta object includes a changedFields object that lists the fields that have changed since the last webhook event was fired (or since the webhook was subscribed to).
CHANGEDFIELDS OBJECT The changedFields object is not available as of this writing but will be added soon.

Example webhook payload with app-specific account ID and changed fields metadata
// Location webhook payload
{
    "location": {
        // Full location object
    },
    "meta": {
        "uuid": "bb0c7e19-4dc3-4891-bfa5-8593b1f124ad",
        "timestamp": 1461191143000,
        "accountId": "12345",
        "appSpecificAccountId": "<APP_SPECIFIC_ACCOUNT_ID>",
        "eventType": "LOCATION_UPDATED",
        "actor": "App 123 - \u0027Hello World App\u0027",
        "changedFields": [
             {"language": “en", "fieldName": "name"},
             {"language": “en", "fieldName": "website"},
        ]
    }
}
More information on the webhook payload can be found in the API documentation.

Webhook events

  • Locations
    • Sends a request whenever a Location is created or modified. The request includes the full details of the affected Location.
  • Menus
    • Sends a request whenever a Menu is created, modified, or deleted. The request includes the full details of the affected Menu.
  • Bios
    • Sends a request whenever a Bio List is created, modified, or deleted. The request includes the full details of the affected Bio List.
  • Products
    • Sends a request whenever a Product List is created, modified, or deleted. The request includes the full details of the affected Product List.
  • Events
    • Sends a request whenever an Event List is created, modified, or deleted. The request includes the full details of the affected Event List.
  • Listing Status
    • Sends a request whenever a Listing’s status changes. The request includes metadata about the Listing, including its new status.
  • Reviews
    • Sends a request whenever a new Review is detected or when an existing Review changes (e.g., a comment is added, the review is revised by its original author, or a response is created or modified).
  • Publisher Suggestions
    • Sends a request whenever an edit has a ‘New’ status and the edit should be saved.
  • Duplicate
    • Sends a request whenever a Duplicate is found, updated, or deleted.
  • Account Unlink
    • Sends a request whenever an account is updated. Currently, the only type of change event is the unlinking of accounts.