English (United States) Čeština Deutsch Español (España) Français (France) Italiano 日本語

Configure Webhooks

Webhooks are a way to configure Yext to push updates to an external application when certain events happen within Yext systems. We recommend subscribing to webhook events rather than polling the API to detect changes in the Knowledge Graph.

Before You Begin

You need:

  • A Yext account
  • A Yext app. If you don't have one yet, see Create an App section of the Get Started with Yext APIs article.
  • Access to the API or APIs for the webhooks you're interested in
  • A URL you want the webhook to send messages to (webhook URL)

Note: To ingest Yext webhook messages, your endpoint must support TLS version 1.2 or higher and have a certificate signed by a widely trusted certificate authority. For more on webhook functionality, see the Webhooks documentation.

Set Up Your Webhook

  1. Go to Developer > Developer Console in the navigation bar and click into your app. If you don't have an app yet, see How to Create an App.
  2. After you're in your app, click Webhooks, then click Add a Webhook.
  3. Select the type of webhook you want to configure and click Next. If you select the Streams webhook, also select which stream you want the webhook to send messages from.
  4. Enter your webhook URL and click Send Test Message.
  5. If the webhook URL returns a successful response, click Finish and Add.
    • If the test fails, review the response body in View Logs, in the left sidebar of your app's details page, to debug the issue.

You can also test your webhook by triggering the action it's meant to notify you about. For example, if you set up the Entities webhook, create or update an entity to trigger a test event. The webhook fires to the URL you configured in the previous step.

Apps Linked to Multiple Yext Accounts

Events for every account linked to your app go to the webhook endpoints you configure. For example, if your app has 10 customers linked to it and you subscribe to the Entities webhook, you receive webhook events for all 10 customers at the same webhook URL. To tell which webhook payload belongs to which Yext account, check the app-specific account ID in the payload's meta object, which matches the value returned during the customer's OAuth process.

Handling Failed Requests

Yext reattempts failed webhook requests as follows:

  • If a webhook request fails, Yext automatically resends it after 5 minutes.
  • If that request also fails, Yext periodically resends it with an exponential backoff over a 24-hour period until it receives a successful response.
  • If Yext doesn't receive a successful response within 24 hours, or after about 8 attempts, it stops retrying the request.

Use Function Hooks

Function hooks let developers trigger functions in response to account and profile events, and can also be accessed through the Webhooks UI.

To invoke a function, first create a function in your account. See Get Started with Yext Functions for steps.

To create a function hook:

  1. Click Developer Console.
  2. Create an app, or click into an existing app.
  3. Click the Webhooks tab.
  4. Click + Add a Webhook.
  5. Select the webhook type.
  6. Enter the webhook details.
  7. Click … or invoke a function.
  8. Click the Select a Function dropdown and select the function to invoke.
  9. Click Finish and Add.

Verify a Webhook Request

You can optionally verify that a webhook request originated from Yext, rather than a potentially malicious third party.

Check for the Configure Security button on the Webhooks page in your Developer Console. If you don't see this button, contact your Client Success Manager or Yext Support to enable this feature for your account.

Yext provides a Signing Secret unique to your app, and includes an X-Yext-Signature header on every webhook request. This header contains the hash of the request body, generated using your Signing Secret. When you receive a request, hash the request body using your Signing Secret. If the result matches the X-Yext-Signature header, the request came from Yext.

Example: verifying a request for an entity update

  1. Get the X-Yext-Signature header from the incoming webhook request:
   yext_signature = request.headers['X-Yext-Signature']
   >> 2eb9d011edb8063d3a2df8057ae772bca7cf6c9d761afcf39dbeea0d810e182b
  1. Get the body from the incoming webhook request:
   request_body = request.body():
   {
     "meta": {
       "eventType": "ENTITY_UPDATED",
       "uuid": "14dec63a-80f3-4aef-8dbc-d39830396fa7",
       "timestamp": 1555090463175,
       "accountId": "2369309",
       "actor": "YEXT SYSTEM",
       "appSpecificAccountId": "50d8bc38a506e9bdba9fcaf103d6811b8212e0d3"
     },
     "entityId": "5600633438974399303",
     "primaryProfile": {
       "address": {
         "line1": "1 Madison Ave",
         "city": "New York",
         "region": "NY",
         "postalCode": "10010",
         "countryCode": "US"
       },
       "addressHidden": false,
       "name": "A location",
       "isoRegionCode": "NY",
       "timezone": "America/New_York",
       "yextDisplayCoordinate": {
         "latitude": 40.7410895,
         "longitude": -73.98750919999999
       },
       "yextRoutableCoordinate": {
         "latitude": 40.7411640951893,
         "longitude": -73.987830606551
       },
       "meta": {
         "accountId": "2369309",
         "uid": "3x7Dmg",
         "id": "5600633438974399303",
         "timestamp": "2019-04-12T17:34:23",
         "folderId": "0",
         "language": "en",
         "countryCode": "US",
         "entityType": "location"
       },
       "categoryIds": ["1857"],
       "reviewGenerationUrl": "https://locationrater.com/tp/2zAkB5",
       "firstPartyReviewPage": "https://www.locationrater.com/survey/YS1sb2NhdGlvbi1uZXcteW9yay1uZXcteW9yay11cy0wM2UzOTc=",
       "timeZoneUtcOffset": "-04:00"
     },
     "languageProfiles": [],
     "changedFields": {
       "language": "en",
       "fieldNames": ["timezone"]
     }
   }
  1. Get your Signing Secret from the Yext platform: click Configure Security in the top right while configuring webhooks for an app, and copy the Signing Secret. This example uses signing_secret = df81b78b32e34680a1c87302bfdefa1a.
  2. Using HMAC SHA256 in your preferred programming language, hash the request body using your Signing Secret as the key, and use the hex digest of the hash:
   my_signature = hmac_sha256_hash(signing_secret, request_body)
   >> 2eb9d011edb8063d3a2df8057ae772bca7cf6c9d761afcf39dbeea0d810e182b
  1. Compare your calculated signature with the signature in the X-Yext-Signature header. If they match, the request came from Yext. If they don't match, block the request and contact API Support to investigate.