Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
All 92 tools →
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/yelp:yelp-webhooks-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Webhooks API
version: '1.0'
servers:
- url: https://api.yelp.com/v3/webhooks/
security:
- bearerAuth: []
tags:
- name: Webhooks
paths:
/:
post:
tags:
- Webhooks
summary: Subscribe to Webhooks
description: 'To subscribe to webhooks for all businesses a Biz Owner has access to
send an authenticated
POST request to the `https://api.yelp.com/v3/webhooks`.
Note: Currently only `leads_event` and `project_update` webhooks
are supported (`NEW_EVENT`, `CONSUMER_PHONE_NUMBER_OPT_IN_EVENT`, `CONSUMER_PHONE_NUMBER_OPT_OUT_EVENT`, `PROJECT_UPDATE`).
## Subscription Expiration
**A webhook subscription will have a default expiration date of 14 days.**
To ensure _no loss of data_, it is recommended you unsubscribe and subscribe again
at least an hour before the expiration date and time.
The `expiration_date` field in the response indicates when the subscription will expire (ISO 8601 format).
Set `expiration_days` to `0` for a subscription that does not expire.
## Payload Signature Verification
All webhook deliveries are signed using Ed25519. To verify the authenticity and integrity of webhook payloads, see Webhook Signature Verification.
Signature verification replaces the previous IP-allowlist workaround. We strongly recommend adopting signature verification for improved security.'
operationId: subscribe_to_webhooks
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
webhook_url:
description: The URL to which the webhook events will be sent.
type: string
format: uri
example: https://example.com/webhook/123
webhook_type:
description: The type of webhook event to subscribe to.
type: string
enum:
- leads_event
- project_update
example: leads_event
restricted_business_ids:
description: 'An optional list of business IDs to restrict the webhook subscription to. If not provided, the webhook will be subscribed to events for all businesses the Biz Owner has access to.
The maximum limit is 50 items.
'
type: array
maxItems: 50
items:
type: string
example: w-WAiKJe__oZV13M34pTFw
expiration_days:
description: 'The number of days until the webhook subscription expires. Default is 14 days.
Set to `0` for a subscription that does not expire.
'
type: integer
minimum: 0
default: 14
required:
- webhook_url
- webhook_type
responses:
'200':
description: 200 OK - Webhook successfully subscribed
content:
application/json:
schema:
type: object
properties:
webhook_id:
description: The unique identifier for the webhook subscription.
type: string
expiration_date:
description: The date and time when the webhook subscription will expire. (ISO 8601 format)
type: string
examples:
Subscription:
value:
webhook_id: VXi7gzRqPKp63X0u6fUtbg
expiration_date: '2023-10-01T12:00:00.000Z'
'400':
$ref: '#/components/schemas/Error400'
'401':
description: 'The API key has either expired or doesn''t have the required scopes to query this endpoint.
| code | description |
| ------------- | ------------- |
| UNAUTHORIZED_API_KEY | The API key provided is not currently able to query this endpoint. |
| TOKEN_INVALID | Invalid API key or authorization header. |
'
content:
application/json:
examples:
Unauthorized:
value:
error:
code: UNAUTHORIZED_API_KEY
description: The API key provided is not currently able to query this endpoint.
Invalid Token:
value:
error:
code: TOKEN_INVALID
description: Invalid API key or authorization header.
schema:
$ref: '#/components/schemas/Error400/content/application~1json/schema'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error400/content/application~1json/schema'
examples:
Conflict:
value:
error:
code: CONFLICT
description: There is a conflict when trying to complete the request.
'429':
description: You have either exceeded your daily quota, or have exceeded the queries-per-second limit for this endpoint. Try reducing the rate at which you make queries.
content:
application/json:
examples:
Rate limited:
value:
error:
code: TOO_MANY_REQUESTS_PER_SECOND
description: You have exceeded the queries-per-second limit for this endpoint. Try reducing the rate at which you make queries.
schema:
$ref: '#/components/schemas/Error400/content/application~1json/schema'
'500':
description: Internal Server Error
content:
application/json:
examples:
Internal Server Error:
value:
error:
code: INTERNAL_ERROR
description: Something went wrong internally, please try again later.
schema:
$ref: '#/components/schemas/Error400/content/application~1json/schema'
/conversions/{vertical}:
post:
tags:
- Webhooks
summary: Linkout Attribution
description: 'The linkout attribution endpoint allows you to connect Yelp events, with relevant events of your service.
## Example
If you provide a booking service and are partnered with Yelp, we will send a linkout URL on business booking events.
The linkout URL will look like: `https://partner.example.com/book?yelp_token=abcd-1234`
You will need to store the provided token for 30 days so it can be linked to further updates.
Then, to update the status of the booking event, send a POST request with a ''booking'' vertical echoing the yelp token from the linkout, like so:
Endpoint: `https://api.yelp.com/v3/webhooks/conversions/booking`
Body:
```json
{
"yelp_token": "abcd-1234",
"event_type": "confirmed",
"event_timestamp": 1774619463560,
"external_id": "123456789",
"original_external_id": "1234567890",
"booking_details_url": "https://partner.example.com/appointments/123456789",
"booked_services": [
{
"title": "Haircut and Style",
"provider": "Mike''s Salon",
"duration_minutes": 60,
"start_datetime": "1774619463560",
"order_value": {
"price": 90.0,
"currency": "USD"
}
},
],
"metadata": {
"stylist_id": "stylist-42",
"first_visit": true
}
}
```
A success will return an empty 200 response.
Note: The format for the authorization header is "Bearer ", i.e. for curl `-H Authorization: Bearer `. For details see Authentication'
operationId: v3_conversion_webhook
parameters:
- name: vertical
in: path
required: true
description: 'Type of conversion being reported. Use `booking` for all booking partners,
including appointment scheduling and restaurant reservations.
'
schema:
type: string
enum:
- booking
- name: dry_run
in: query
required: false
description: 'Allows for testing the request without enacting any lasting changes.
The endpoint will respond with an appropriate error response if there are issues with the request, or with success if there were no issues found.
'
schema:
type: boolean
default: false
requestBody:
required: true
description: Generic partner attribution request body
content:
application/json:
schema:
$ref: '#/components/schemas/GenericAttributionWebhookRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
examples:
Success: {}
'400':
description: Bad request
content:
application/json:
examples:
Missing API Key:
value:
error:
code: VALIDATION_ERROR
description: Authorization is a required parameter.
API Key is too short:
value:
error:
code: VALIDATION_ERROR
description: Bearer INVALID_KEY does not match ^(?i)Bearer [A-Za-z0-9\\\\-\\\\_]{128}$
Invalid yelp_token:
value:
error:
code: BAD_REQUEST
description: The request is not valid.
Missing yelp_token:
value:
error:
code: VALIDATION_ERROR
description: yelp_token is a required property
Missing event_type:
value:
error:
code: VALIDATION_ERROR
description: event_type is a required property
Invalid event_type:
value:
error:
code: VALIDATION_ERROR
description: invalid is not one of [confirmed, canceled, rescheduled]
Stale Timestamp:
value:
error:
code: BAD_REQUEST
description: The request is not valid.
schema:
$ref: '#/components/schemas/Error400/content/application~1json/schema'
'401':
description: Unauthorized - Unauthorized API key
content:
application/json:
examples:
Unauthorized API Key:
value:
error:
code: UNAUTHORIZED_ACCESS_TOKEN
description: The access token provided is not currently able to query this endpoint.
schema:
$ref: '#/components/schemas/Error400/content/application~1json/schema'
'404':
description: Not Found - Query vertical not found
content:
application/json:
examples:
Invalid request vertical:
value:
error:
code: NOT_FOUND
description: Resource could not be found.
schema:
$ref: '#/components/schemas/Error400/content/application~1json/schema'
/keys:
get:
tags:
- Webhooks
summary: Get Webhook Signing Keys
description: 'Returns the current set of public keys used to sign webhook payloads, in JSON Web Key Set (JWKS) format.
Use these keys to verify the `X-Yelp-Webhook-Signature` header on incoming webhook deliveries.
During key rotation, multiple keys may be returned — use the `kid` field to match the key specified in the `X-Yelp-Webhook-Key-Id` delivery header.
This endpoint does not require authentication and is rate-limited.
For full verification documentation and code examples, see Webhook Signature Verification.'
operationId: get_webhook_signing_keys
responses:
'200':
description: The current set of webhook signing public keys.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookKeySet'
examples:
Single Key:
value:
keys:
- kty: OKP
crv: Ed25519
kid: 2026-06-v1
use: sig
x: ffqFbtjg3OeXpUtTMRAk1otf6Y2dj9I6m-37BLGB9qk
Multiple Keys (during rotation):
value:
keys:
- kty: OKP
crv: Ed25519
kid: 2026-06-v1
use: sig
x: ffqFbtjg3OeXpUtTMRAk1otf6Y2dj9I6m-37BLGB9qk
- kty: OKP
crv: Ed25519
kid: 2026-07-v1
use: sig
x: abc123def456ghi789jkl012mno345pqr678stu901vwx
'429':
$ref: '#/paths/~1/post/responses/429'
'500':
$ref: '#/paths/~1/post/responses/500'
/whitelists/businesses/add:
post:
deprecated: true
tags:
- Webhooks
summary: Add Business IDs to Allow List
description: 'Add business IDs to Allow List.
Example:
If you want to add the following two business IDs, send a POST request with the following JSON body:
```json
{
"business_ids": [
"w-WAiKJe__oZV13M34pTFw",
"ThncHZzfDNaNYYMXk88hLQ"
]
}
```
A successful response will show the number of businesses in your allow list.
For the above example:
```json
{"whitelist_business_ids_count": 2}
```
Note: The format for the authorization header is "Bearer ", i.e. for curl `-H Authorization: Bearer `. For details see Authentication'
operationId: add_businesses_to_allow_list
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
business_ids:
description: A list of Yelp Business IDs
type: array
minItems: 1
maxItems: 100
items:
description: Yelp Business IDs
type: string
examples:
- w-WAiKJe__oZV13M34pTFw
- ThncHZzfDNaNYYMXk88hLQ
required:
- business_ids
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/AddRemoveBusinessesToAllowListResponse'
examples:
Result:
value:
whitelist_business_ids_count: 2
'400':
$ref: '#/components/schemas/Error400'
'401':
$ref: '#/paths/~1/post/responses/401'
'404':
$ref: '#/components/schemas/Error404'
'429':
$ref: '#/paths/~1/post/responses/429'
'500':
$ref: '#/paths/~1/post/responses/500'
/whitelists/businesses/remove:
post:
deprecated: true
tags:
- Webhooks
summary: Remove Business IDs from Allow List
description: 'Remove business IDs from Allow List.
Example:
If you want to remove the following two business IDs, send a POST request with the following JSON body:
```json
{
"business_ids": [
"w-WAiKJe__oZV13M34pTFw",
"ThncHZzfDNaNYYMXk88hLQ"
]
}
```
A successful response will show the number of businesses in your allow list.
For the above example:
```json
{"whitelist_business_ids_count": 0}
```
Note: The format for the authorization header is "Bearer ", i.e. for curl `-H Authorization: Bearer `. For details see Authentication'
operationId: remove_businesses_to_allow_list
requestBody:
required: true
content:
application/json:
schema:
type: object
examples:
- business_ids:
- '1'
- '2'
properties:
business_ids:
description: A list of Yelp Business IDs
type: array
minItems: 1
maxItems: 100
items:
description: Yelp Business IDs
type: string
examples:
- w-WAiKJe__oZV13M34pTFw
- ThncHZzfDNaNYYMXk88hLQ
required:
- business_ids
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/AddRemoveBusinessesToAllowListResponse'
examples:
Result:
value:
whitelist_business_ids_count: 2
'400':
$ref: '#/components/schemas/Error400'
'401':
$ref: '#/paths/~1/post/responses/401'
'404':
$ref: '#/components/schemas/Error404'
'429':
$ref: '#/paths/~1/post/responses/429'
'500':
$ref: '#/paths/~1/post/responses/500'
/{webhook_id}:
delete:
tags:
- Webhooks
summary: Unsubscribe to Webhook
description: 'Unsubscribe from a webhook subscription using the `webhook_id` obtained during the subscription process.
Use an authenticated
DELETE to the `https://api.yelp.com/v3/webhooks/{webhook_id}` endpoint.'
operationId: unsubscribe_to_webhook
parameters:
- name: webhook_id
in: path
required: true
description: The unique identifier for the webhook subscription.
schema:
type: string
responses:
'204':
description: 204 No Content - Webhook successfully unsubscribed
content:
application/json:
schema:
type: object
examples:
Success: {}
'400':
$ref: '#/components/schemas/Error400'
'401':
$ref: '#/paths/~1/post/responses/401'
'404':
$ref: '#/components/schemas/Error404'
'429':
$ref: '#/paths/~1/post/responses/429'
'500':
$ref: '#/paths/~1/post/responses/500'
components:
schemas:
Error400:
description: Bad Request
content:
application/json:
examples:
Invalid Client ID:
value:
error:
code: VALIDATION_ERROR
description: IvStoCVyoXPH3WNPf83d1A is not a valid client ID.
One or more business IDs were invalid:
value:
error:
code: VALIDATION_ERROR
description: 'Invalid business IDs found: w-WAiKJe__oZV13M34pTFw.'
Exactly zero businesses are not allowed:
value:
error:
code: VALIDATION_ERROR
description: No business IDs provided.
More than the maximum number (100) of businesses is not allowed:
value:
error:
code: VALIDATION_ERROR
description: '[IDs] exceeds max update size of 100.'
schema:
type: object
properties:
error:
type: object
required:
- code
- description
properties:
code:
type: string
description: The error code.
description:
type: string
description: The description of the error.
WebhookKey:
type: object
description: A JSON Web Key (JWK) representing an Ed25519 public key used to verify webhook payload signatures.
properties:
kty:
description: Key type. Always `OKP` for Ed25519 keys.
type: string
enum:
- OKP
crv:
description: Curve name. Always `Ed25519`.
type: string
enum:
- Ed25519
kid:
description: Key ID. Matches the `X-Yelp-Webhook-Key-Id` header on webhook deliveries, allowing you to select the correct key for verification.
type: string
use:
description: Key usage. Always `sig` (signature).
type: string
enum:
- sig
x:
description: The Base64url-encoded public key material.
type: string
required:
- kty
- crv
- kid
- use
- x
WebhookKeySet:
type: object
properties:
keys:
description: An array of JSON Web Keys (JWK) used to verify webhook signatures.
type: array
items:
$ref: '#/components/schemas/WebhookKey'
required:
- keys
AddRemoveBusinessesToAllowListResponse:
type: object
properties:
whitelist_business_ids_count:
description: The number of businesses in your allow list.
type: number
required:
- whitelist_business_ids_count
GenericAttributionWebhookRequest:
type: object
properties:
yelp_token:
type: string
description: 'The Base64 encoded string passed by query parameter of linkout URL, and stored by the partner.
Has to be included in the webhook event associated with the original linkout.
Food ordering partners may instead send the click id Yelp appended to the linkout URL.
'
event_type:
type: string
description: Booking event type
enum:
- confirmed
- canceled
- rescheduled
event_timestamp:
type: integer
description: Epoch timestamp of event, in milliseconds
external_id:
type: string
description: External id in the partner domain representing the booking
original_external_id:
type: string
description: For "rescheduled" events, this will be the original booking id if a new one has been created
external_business_id:
type: string
description: 'For events where a user decided to still go through with the booking, but with a different biz.
This is the partner encoded biz id, which will be associated with Yelp biz id server-side.
'
booking_details_url:
type: string
description: Callback URL for Yelp to directly retrieve the details of the booking
booked_services:
type: array
items:
$ref: '#/components/schemas/BookedService'
metadata:
type: object
additionalProperties: true
description: Optional partner-specific details about the booking, e.g. party size or seating area. Stored for reporting and not validated.
required:
- yelp_token
- event_type
- event_timestamp
- external_id
BookedService:
description: Formatted booking details
type: object
properties:
title:
type: string
description: The service name
provider:
type: string
description: The service provider name
duration_minutes:
type: integer
description: Duration of the appointment, in minutes
start_datetime:
type: integer
description: Start datetime of the appointment, Epoch timestamp in milliseconds
order_value:
$ref: '#/components/schemas/OrderValue'
Error404:
description: You are not signed up to use this service.
content:
application/json:
examples:
Result:
value:
error:
code: NOT_FOUND
description: Resource could not be found.
schema:
$ref: '#/components/schemas/Error400/content/application~1json/schema'
OrderValue:
description: Gross Order Value (GOV) of the service
type: object
properties:
price:
type: number
description: Order value
currency:
type: string
description: ISO-4217 currency code, "USD" by default
required:
- price
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'To authenticate API calls with the API Key, set the Authorization HTTP header value as `Bearer API_KEY`.
Example: `Bearer 23813239889e947efd3e787cc41b0b839f442a85c5bfd30bd4b9a85ec3a54d5cae4d52b37ff52e64deb9c83bd04883812a6cebde04f2f25752f31be0ac74b514`.
You can create or find your API Key at [yelp.com](https://www.yelp.com/developers/v3/manage_app).
'
x-provenance:
method: searched
source: https://docs.developer.yelp.com/reference
harvested: '2026-11-05'
tool: harvest-readme-openapi.py
note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
assembled_from:
- https://docs.developer.yelp.com/reference/add_businesses_to_allow_list.md
- https://docs.developer.yelp.com/reference/get_webhook_signing_keys.md
- https://docs.developer.yelp.com/reference/remove_businesses_to_allow_list.md
- https://docs.developer.yelp.com/reference/subscribe_to_webhooks.md
- https://docs.developer.yelp.com/reference/unsubscribe_to_webhook.md
- https://docs.developer.yelp.com/reference/v3_conversion_webhook.md
merge:
pages: 6
deduped: 17
conflicts_kept_first: 0