Overview

Webhooks are reserved for use only by official Yelp advertising, listing management, & knowledge partners. If interested in using webhooks, please inquire about becoming a partner via one of those pages.

Webhooks will allow you to get real-time notifications to certain events on Yelp. When one of these events is triggered, we'll send an HTTP POST payload to the webhook's configured URL. For example, webhooks can be used to be notified of a new review for a given business, when a Data Ingestion API job has been updated, when a license is verified or a business receives a new lead. If you experience any issues with the system or if you have questions, feel free to contact us at [email protected]

Initial Setup

Become an official Yelp advertising, listing management, or knowledge partner.
Only after you're become an official partner, CC your Yelp rep and email [email protected]:
- Your Yelp Fusion client ID
- The webhook URL that will receive HTTP POST requests
We will send a verification request to the webhook URL you provide, and expect to get back a particular response in order to finalize registration of your webhook URL. Please see "Verification Flow" below for full details.
As soon as verification is complete, Yelp's webhooks system will begin to send POST requests for the configured event types and subscribed businesses. To add or remove business IDs from your allow list, please see the "Adding and Removing Allow List Business IDs via API" section.

Verification Flow

To verify your webhook URL, we will send a GET request to your webhook URL with a query parameter, verification. The query parameter will be a string of alphanumeric English characters. For example, if your webhook URL is https://www.<DOMAIN>.com/webhooks then you should expect to be sent a GET request like:

curl -X GET https://www.<DOMAIN>.com/webhooks?verification=your_verification_string

To complete the verification, we are expecting your servers to respond to this message with a JSON response that includes the verification string in the following format:

{"verification": "your_verification_string"}

Please note that the URL to which we send the GET request will also be the same URL to which we send POST requests.

The two ways that webhook URL verification can fail are:

The webhook URL does not exist, i.e. HTTP 404
The webhook URL exists, but when Yelp sends the verification GET request there is either no response (i.e. request times out) or the response does not conform to the format described above.

Yelp will not automatically retry webhook URL verification; it is a process triggered manually by a Yelp employee. Please email [email protected] when you are ready for Yelp to begin the URL verification process.

Webhook endpoint

Once your webhook is verified Yelp will begin sending POST requests to that url.

Your endpoint should respond to all requests:

with a 2XX HTTP response
within 10 seconds or less

#!/usr/bin/python
from flask import Flask
from flask import request
import json
import os

app = Flask(__name__)
 

@app.route('/')
def index():
    return json.dumps(request.args)

@app.route('/', methods=["POST"])
def index_post():
    webhook_payload = json.loads(request.data)
    print("webhook_payload", webhook_payload)
    
    ...

    return '', 201


if __name__ == '__main__':
    port = int(os.environ.get("PORT", 5001))
    app.run(host='0.0.0.0', port=port, threaded=False, processes=1)

Retries

When Yelp attempts to send a message (POST request of data) to your configured webhook URL and your server responds with an HTTP response other 2XX, or does not respond at all (request times out) we will assume that message was not successfully delivered to you. Yelp will then retry sending that message at intervals for up to 24 hours. After a message has been unsuccessfully retried for over 24 hours, it will be discarded.

Order

Due to retries and other factors, it is very likely that your systems will not receive messages in the same order they were generated by Yelp. Every message sent includes at least one timestamp that you should use to determine where that message's data fits in chronological order. These timestamps can also assist in de-duplicating messages.

Subscribe to businesses to receive webhooks

You can use the Business Subscriptions API with the subscription type WEBHOOK to subscribe or unsubscribe from getting webhook notifications for specific businesses.

docs.developer.yelp.com

Business Subscriptions API

FAQs

Can you share the list of IP addresses that might send us webhooks?

Yes, request this list via [email protected].