The Airbnb Webhooks API enables connectivity partners to receive real-time notifications when events occur on the Airbnb platform. It supports webhook subscriptions for reservation changes, message creation, review submissions, listing calendar updates, and other key events.
asyncapi: 2.6.0
info:
title: Airbnb Webhooks API
description: >-
The Airbnb Webhooks API enables connectivity partners to receive
real-time notifications when events occur on the Airbnb platform. It
supports webhook subscriptions for reservation changes, message creation,
review submissions, listing calendar updates, and other key events.
Partners can subscribe to events such as reservation confirmations,
cancellations, guest messages, new reviews, and availability or pricing
changes, allowing their systems to react immediately without needing to
poll the API for updates.
version: '2025.03.31'
contact:
name: Airbnb Developer Support
url: https://developer.withairbnb.com/
externalDocs:
description: Airbnb Developer Documentation
url: https://developer.withairbnb.com/
servers:
partnerWebhookEndpoint:
url: '{webhookUrl}'
protocol: https
description: >-
The partner-configured HTTPS endpoint that receives webhook
notifications from Airbnb. Partners register their webhook URL
through the Airbnb developer portal.
variables:
webhookUrl:
description: >-
The partner HTTPS URL configured to receive webhook events.
security:
- signatureVerification: []
channels:
/webhook:
description: >-
The webhook endpoint that receives all Airbnb event notifications.
Events are delivered as HTTP POST requests with a JSON payload.
Each event includes a type field to identify the event category
and a signature header for verification.
publish:
operationId: receiveWebhookEvent
summary: Receive an Airbnb webhook event
description: >-
Airbnb sends event notifications to the partner webhook endpoint
when relevant changes occur on the platform. Partners should
respond with a 200 status code to acknowledge receipt. Events
that are not acknowledged may be retried.
message:
oneOf:
- $ref: '#/components/messages/ReservationCreated'
- $ref: '#/components/messages/ReservationConfirmed'
- $ref: '#/components/messages/ReservationCancelled'
- $ref: '#/components/messages/ReservationUpdated'
- $ref: '#/components/messages/ReservationCheckedIn'
- $ref: '#/components/messages/ReservationCheckedOut'
- $ref: '#/components/messages/MessageCreated'
- $ref: '#/components/messages/ReviewSubmitted'
- $ref: '#/components/messages/CalendarUpdated'
- $ref: '#/components/messages/ListingUpdated'
- $ref: '#/components/messages/PricingUpdated'
- $ref: '#/components/messages/BookingCreated'
- $ref: '#/components/messages/BookingConfirmed'
- $ref: '#/components/messages/BookingCancelled'
components:
securitySchemes:
signatureVerification:
type: httpApiKey
name: X-Airbnb-Signature
in: header
description: >-
Airbnb signs each webhook payload using HMAC-SHA256 with the
partner webhook secret. Partners must verify the signature in
the X-Airbnb-Signature header to ensure the request originated
from Airbnb and has not been tampered with.
messages:
ReservationCreated:
name: reservation.created
title: Reservation Created
summary: >-
Sent when a new reservation request is created by a guest.
contentType: application/json
payload:
$ref: '#/components/schemas/ReservationEvent'
headers:
type: object
properties:
X-Airbnb-Signature:
type: string
description: >-
HMAC-SHA256 signature of the request body.
X-Airbnb-Event-Type:
type: string
const: reservation.created
description: >-
The type of webhook event.
ReservationConfirmed:
name: reservation.confirmed
title: Reservation Confirmed
summary: >-
Sent when a reservation is confirmed by the host or automatically
through instant booking.
contentType: application/json
payload:
$ref: '#/components/schemas/ReservationEvent'
headers:
type: object
properties:
X-Airbnb-Signature:
type: string
description: >-
HMAC-SHA256 signature of the request body.
X-Airbnb-Event-Type:
type: string
const: reservation.confirmed
description: >-
The type of webhook event.
ReservationCancelled:
name: reservation.cancelled
title: Reservation Cancelled
summary: >-
Sent when a reservation is cancelled by either the host or guest.
contentType: application/json
payload:
$ref: '#/components/schemas/ReservationCancellationEvent'
headers:
type: object
properties:
X-Airbnb-Signature:
type: string
description: >-
HMAC-SHA256 signature of the request body.
X-Airbnb-Event-Type:
type: string
const: reservation.cancelled
description: >-
The type of webhook event.
ReservationUpdated:
name: reservation.updated
title: Reservation Updated
summary: >-
Sent when a reservation is modified, such as date changes or
guest count updates.
contentType: application/json
payload:
$ref: '#/components/schemas/ReservationEvent'
headers:
type: object
properties:
X-Airbnb-Signature:
type: string
description: >-
HMAC-SHA256 signature of the request body.
X-Airbnb-Event-Type:
type: string
const: reservation.updated
description: >-
The type of webhook event.
ReservationCheckedIn:
name: reservation.checked_in
title: Reservation Checked In
summary: >-
Sent when a guest checks in to the property.
contentType: application/json
payload:
$ref: '#/components/schemas/ReservationEvent'
headers:
type: object
properties:
X-Airbnb-Signature:
type: string
description: >-
HMAC-SHA256 signature of the request body.
X-Airbnb-Event-Type:
type: string
const: reservation.checked_in
description: >-
The type of webhook event.
ReservationCheckedOut:
name: reservation.checked_out
title: Reservation Checked Out
summary: >-
Sent when a guest checks out of the property.
contentType: application/json
payload:
$ref: '#/components/schemas/ReservationEvent'
headers:
type: object
properties:
X-Airbnb-Signature:
type: string
description: >-
HMAC-SHA256 signature of the request body.
X-Airbnb-Event-Type:
type: string
const: reservation.checked_out
description: >-
The type of webhook event.
MessageCreated:
name: message.created
title: Message Created
summary: >-
Sent when a new message is created in a reservation thread by
either the host or guest.
contentType: application/json
payload:
$ref: '#/components/schemas/MessageEvent'
headers:
type: object
properties:
X-Airbnb-Signature:
type: string
description: >-
HMAC-SHA256 signature of the request body.
X-Airbnb-Event-Type:
type: string
const: message.created
description: >-
The type of webhook event.
ReviewSubmitted:
name: review.submitted
title: Review Submitted
summary: >-
Sent when a new review is submitted by a guest for a completed
reservation.
contentType: application/json
payload:
$ref: '#/components/schemas/ReviewEvent'
headers:
type: object
properties:
X-Airbnb-Signature:
type: string
description: >-
HMAC-SHA256 signature of the request body.
X-Airbnb-Event-Type:
type: string
const: review.submitted
description: >-
The type of webhook event.
CalendarUpdated:
name: calendar.updated
title: Calendar Updated
summary: >-
Sent when the availability calendar for a listing is updated,
including blocked dates and availability changes.
contentType: application/json
payload:
$ref: '#/components/schemas/CalendarEvent'
headers:
type: object
properties:
X-Airbnb-Signature:
type: string
description: >-
HMAC-SHA256 signature of the request body.
X-Airbnb-Event-Type:
type: string
const: calendar.updated
description: >-
The type of webhook event.
ListingUpdated:
name: listing.updated
title: Listing Updated
summary: >-
Sent when a listing is updated, including changes to description,
amenities, photos, or status.
contentType: application/json
payload:
$ref: '#/components/schemas/ListingEvent'
headers:
type: object
properties:
X-Airbnb-Signature:
type: string
description: >-
HMAC-SHA256 signature of the request body.
X-Airbnb-Event-Type:
type: string
const: listing.updated
description: >-
The type of webhook event.
PricingUpdated:
name: pricing.updated
title: Pricing Updated
summary: >-
Sent when the pricing for a listing is changed, including nightly
rates, cleaning fees, and discount rules.
contentType: application/json
payload:
$ref: '#/components/schemas/PricingEvent'
headers:
type: object
properties:
X-Airbnb-Signature:
type: string
description: >-
HMAC-SHA256 signature of the request body.
X-Airbnb-Event-Type:
type: string
const: pricing.updated
description: >-
The type of webhook event.
BookingCreated:
name: booking.created
title: Experience Booking Created
summary: >-
Sent when a new experience booking is created by a guest.
contentType: application/json
payload:
$ref: '#/components/schemas/BookingEvent'
headers:
type: object
properties:
X-Airbnb-Signature:
type: string
description: >-
HMAC-SHA256 signature of the request body.
X-Airbnb-Event-Type:
type: string
const: booking.created
description: >-
The type of webhook event.
BookingConfirmed:
name: booking.confirmed
title: Experience Booking Confirmed
summary: >-
Sent when an experience booking is confirmed by the host.
contentType: application/json
payload:
$ref: '#/components/schemas/BookingEvent'
headers:
type: object
properties:
X-Airbnb-Signature:
type: string
description: >-
HMAC-SHA256 signature of the request body.
X-Airbnb-Event-Type:
type: string
const: booking.confirmed
description: >-
The type of webhook event.
BookingCancelled:
name: booking.cancelled
title: Experience Booking Cancelled
summary: >-
Sent when an experience booking is cancelled.
contentType: application/json
payload:
$ref: '#/components/schemas/BookingEvent'
headers:
type: object
properties:
X-Airbnb-Signature:
type: string
description: >-
HMAC-SHA256 signature of the request body.
X-Airbnb-Event-Type:
type: string
const: booking.cancelled
description: >-
The type of webhook event.
schemas:
WebhookEventBase:
type: object
required:
- event_id
- event_type
- timestamp
properties:
event_id:
type: string
description: >-
A unique identifier for this webhook event, used for
idempotency and deduplication.
event_type:
type: string
description: >-
The type of event that triggered the webhook notification.
timestamp:
type: string
format: date-time
description: >-
The ISO 8601 timestamp when the event occurred.
api_version:
type: string
description: >-
The API version used for the webhook payload format.
ReservationEvent:
allOf:
- $ref: '#/components/schemas/WebhookEventBase'
- type: object
required:
- data
properties:
data:
type: object
required:
- reservation_id
- listing_id
- status
properties:
reservation_id:
type: string
description: >-
The unique identifier of the reservation.
confirmation_code:
type: string
description: >-
The human-readable confirmation code.
listing_id:
type: string
description: >-
The identifier of the associated listing.
status:
type: string
description: >-
The current status of the reservation.
enum:
- pending
- accepted
- denied
- cancelled
- checked_in
- checked_out
guest_id:
type: string
description: >-
The identifier of the guest.
check_in:
type: string
format: date
description: >-
The guest check-in date.
check_out:
type: string
format: date
description: >-
The guest check-out date.
guests_count:
type: integer
description: >-
The number of guests in the reservation.
total_price:
type: number
format: double
description: >-
The total price of the reservation.
currency:
type: string
description: >-
The ISO 4217 currency code.
pattern: '^[A-Z]{3}$'
ReservationCancellationEvent:
allOf:
- $ref: '#/components/schemas/WebhookEventBase'
- type: object
required:
- data
properties:
data:
type: object
required:
- reservation_id
- listing_id
- status
properties:
reservation_id:
type: string
description: >-
The unique identifier of the cancelled reservation.
confirmation_code:
type: string
description: >-
The human-readable confirmation code.
listing_id:
type: string
description: >-
The identifier of the associated listing.
status:
type: string
const: cancelled
description: >-
The cancelled status of the reservation.
cancelled_by:
type: string
description: >-
Who initiated the cancellation.
enum:
- host
- guest
- airbnb
cancellation_reason:
type: string
description: >-
The reason provided for the cancellation.
refund_amount:
type: number
format: double
description: >-
The amount refunded to the guest.
currency:
type: string
description: >-
The ISO 4217 currency code.
pattern: '^[A-Z]{3}$'
MessageEvent:
allOf:
- $ref: '#/components/schemas/WebhookEventBase'
- type: object
required:
- data
properties:
data:
type: object
required:
- message_id
- reservation_id
- sender_type
properties:
message_id:
type: string
description: >-
The unique identifier of the message.
reservation_id:
type: string
description: >-
The identifier of the associated reservation.
sender_type:
type: string
description: >-
Whether the message was sent by the host or guest.
enum:
- host
- guest
message_preview:
type: string
description: >-
A truncated preview of the message content.
maxLength: 200
ReviewEvent:
allOf:
- $ref: '#/components/schemas/WebhookEventBase'
- type: object
required:
- data
properties:
data:
type: object
required:
- review_id
- reservation_id
- reviewer_type
properties:
review_id:
type: string
description: >-
The unique identifier of the review.
reservation_id:
type: string
description: >-
The identifier of the associated reservation.
listing_id:
type: string
description: >-
The identifier of the reviewed listing.
reviewer_type:
type: string
description: >-
Whether the review was submitted by a guest or host.
enum:
- guest
- host
rating:
type: integer
description: >-
The overall star rating from 1 to 5.
minimum: 1
maximum: 5
CalendarEvent:
allOf:
- $ref: '#/components/schemas/WebhookEventBase'
- type: object
required:
- data
properties:
data:
type: object
required:
- listing_id
- start_date
- end_date
properties:
listing_id:
type: string
description: >-
The identifier of the listing whose calendar changed.
start_date:
type: string
format: date
description: >-
The start of the date range that was updated.
end_date:
type: string
format: date
description: >-
The end of the date range that was updated.
change_type:
type: string
description: >-
The type of calendar change that occurred.
enum:
- availability
- blocked
- reservation
ListingEvent:
allOf:
- $ref: '#/components/schemas/WebhookEventBase'
- type: object
required:
- data
properties:
data:
type: object
required:
- listing_id
properties:
listing_id:
type: string
description: >-
The identifier of the listing that was updated.
changed_fields:
type: array
description: >-
The fields that were modified on the listing.
items:
type: string
status:
type: string
description: >-
The current status of the listing.
enum:
- active
- inactive
- pending
- unlisted
PricingEvent:
allOf:
- $ref: '#/components/schemas/WebhookEventBase'
- type: object
required:
- data
properties:
data:
type: object
required:
- listing_id
properties:
listing_id:
type: string
description: >-
The identifier of the listing whose pricing changed.
changed_fields:
type: array
description: >-
The pricing fields that were modified.
items:
type: string
enum:
- nightly_price
- cleaning_fee
- weekly_discount
- monthly_discount
- extra_guest_fee
effective_date:
type: string
format: date
description: >-
The date from which the pricing changes take effect.
BookingEvent:
allOf:
- $ref: '#/components/schemas/WebhookEventBase'
- type: object
required:
- data
properties:
data:
type: object
required:
- booking_id
- experience_id
- status
properties:
booking_id:
type: string
description: >-
The unique identifier of the experience booking.
confirmation_code:
type: string
description: >-
The human-readable confirmation code.
experience_id:
type: string
description: >-
The identifier of the associated experience.
schedule_id:
type: string
description: >-
The identifier of the booked schedule slot.
status:
type: string
description: >-
The current status of the booking.
enum:
- pending
- confirmed
- cancelled
- completed
guest_id:
type: string
description: >-
The identifier of the guest.
guests_count:
type: integer
description: >-
The number of guests in the booking.