📘

Get started with webhooks here

This page described the details of the Leads API Webhooks. For the general webhook setup please see Webhooks first.

Format of Webhook Messages

A Webhook POST request body is a JSON object with the following format:

Full Webhook Payload

Webhooks will include a timestamp, a "business" object and data related to the lead.

{
  // Yelp processing time
  "time": "2022-06-09T09:41:14+00:00",
  // always business
  "object": "business",
  "data": {
    // Yelp Business ID
    "id": "SoVHhx7Hel_XX0DKCLp72Q",
    // updates is an array of updates/webhook events. 
    // For Leads Webhooks this will always be 1 entry with the event_type NEW_EVENT. 
    // Other Yelp Webhooks may include a different number of updates with different (from NEW_EVENT) event_type's 
    "updates": [
      {
        // The event type. For Leads API always NEW_EVENT
        "event_type": "NEW_EVENT",
        // The unique ID of this event
        "event_id": "IsKxQAYZNqCjvRRmNoiCUw",
        // The ID of the lead this event happened on
        "lead_id": "TbvEUYEi02cmSBmqCjQbkg",
        // The time this event was created by the user
        "interaction_time": "2022-06-09T09:41:13+00:00"
      }
    ]
  }
}

Webhook delivery

What interactions on Yelp trigger a Webhook?

Once the webhook setup is completed, you'll be notified when:

• A new lead is created
• A new interaction is done in an existing lead, for example a new message is sent.

When are webhooks sent?

Webhooks are sent whenever an event starts showing on Yelp for Business. This can be significantly later than when the user interacted on Yelp in some cases, see below.

Most webhooks are sent out within a minute or less after showing up on Yelp. While we don't provide any guarantees, our aim is to deliver 99% of webhooks within 2 hours 30 minutes.

Why is there a delay between interaction_time and when the webhook is sent?

Some events are not eligible to be shown on Yelp immediately. The two most common case are:

Spam: Yelp may quarantine messages for some time (minutes, hours, days). Webhooks are sent whenever a message is also eligible to be shown on Yelp, which may differ significantly from the timestamps in a message.

Events displayed delayed on Yelp: Some kind of events may show a significant delay between when the user interacted with a Lead and when the interaction is shown on Yelp and you are notified. This is intentional.

One example for this are consumer hire resolution events where a Yelp User marks your or another business's Lead as hired, you'll receive a message text such as "Automatic message:\\nUser U. has indicated they have booked another business for this job.".

If the business responds directly on Yelp, will I get notified?

Yelp Webhook notifies you of all interactions on a Lead no matter the source. This means you will get notified for interactions on Yelp and through the API from both consumer and business users (including events you create yourself).

Why isn't the message text in the webhook?

Yelp Webhook currently does not return full events. You can obtain the lead_id in the Webhook, and use the Get Lead Events Endpoint to get the full event content (message text, attachments or other).

Can we add your IP addresses to an allow list to verify the requests are coming from Yelp?

Yes, we can share the list of IPs that will send webhook payloads.

FAQs

Please see also the Leads API FAQs:

docs.developer.yelp.com

Leads API FAQs