1. Webhooks
WinCloud API
  • Getting Started
    • Introduction
    • Quick Start
    • Authentication
    • General
    • Changelog
    • Privacy Policy
    • Terms of Service
    • Support
  • APIs
    • Guests
      • Search Guests
      • Create Guest
      • Get Guest Details
      • Update Guest
      • Get Guest Reservations
      • Get Guest Reference Data
    • Inventory
      • Get Room Inventory
      • Get Room Inventory Details
      • Update Room Inventory
    • Properties
      • Get Customer Properties
      • Get Property Configuration
    • Rates
      • Get Rate Adjustment Templates
      • Get Master Rates
      • Post Master Rates
      • Post Individual Rates
    • Reference Data
      • Get Countries
      • Get Payment Gateways
      • Get Payment Methods
      • Get Currencies
    • Reservations v1
      • Get Reservations
      • Get Cancelled Reservations
      • Get No-Show Reservations
      • Get Reservation Statuses
      • Update Special Instructions
    • Reservations v2
      • List Reservations
      • Get Reservation
    • Rooms
      • Get Rooms
      • Get Room Types
      • Get Rooms Extra Charges
      • Get Rooms Feature Types
      • Get Rooms Tariffs
      • Get Room and Revenue Performance
    • Travel Agents
      • Get Active Travel Agents
    • POS
      • Get Outlet Menu
    • Booking Analytics
      • Get Arrival Summary
      • Get Booking Summary
    • Schemas
      • CodeNameDto
      • ArrivalFiguresDto
      • CompanyDto
      • ArrivalSummaryDto
      • CompanyDtoPaginatedResponse
      • ArrivalSummaryDtoApiResponse
      • CompanyDtoPaginatedResponseApiResponse
      • BookingSummaryDto
      • CountryDto
      • ConfigurationOutletDto
      • BookingSummaryDtoApiResponse
      • CountryDtoApiResponse
      • ConfigurationRoomTypeDto
      • CountryRefDto
      • CurrencyDto
      • CurrencyDtoPaginatedResponse
      • CurrencyDtoPaginatedResponseApiResponse
      • ExtraChargeDto
      • ExtraChargeDtoApiResponse
      • FeatureTypeDto
      • CurrencyRefDto
      • FeatureTypeDtoPaginatedResponse
      • FeatureTypeDtoPaginatedResponseApiResponse
      • GuestCreatedDto
      • GuestAddressDto
      • GuestCreatedDtoApiResponse
      • GuestLookupsDto
      • GuestLookupsDtoApiResponse
      • DepartureFiguresDto
      • GuestPhoneDto
      • GuestPreferencesDto
      • GuestProfileDtoApiResponse
      • GuestProfileDto
      • GuestReservationDtoPaginatedResponse
      • GuestReservationDtoPaginatedResponseApiResponse
      • GuestStaySummaryDto
      • GuestReservationDto
      • GuestProfileRequestDto
      • GuestSummaryItemDto
      • GuestSummaryItemDtoPaginatedResponse
      • GuestPassportDto
      • GuestSummaryItemDtoPaginatedResponseApiResponse
      • InventoryRoomTypeDto
      • InventorySnapshotDto
      • InventorySnapshotDtoPaginatedResponse
      • InventorySnapshotDtoPaginatedResponseApiResponse
      • LanguageRefDto
      • MasterRateBlockDto
      • MasterRateTypeDto
      • MasterRateTypeDtoPaginatedResponse
      • MasterRateTypeDtoPaginatedResponseApiResponse
      • LinkedGuestDto
      • MealPlanDto
      • ObjectApiResponse
      • PayMethodDto
      • PayMethodDtoPaginatedResponse
      • OtaReferenceDto
      • PayMethodDtoPaginatedResponseApiResponse
      • PaymentGatewayDto
      • PaymentGatewayDtoPaginatedResponse
      • PaymentGatewayDtoPaginatedResponseApiResponse
      • ProblemDetails
      • PosMenuItemDto
      • RateAdjustmentTemplateDto
      • PosMenuItemDtoPaginatedResponse
      • RateAdjustmentTemplateDtoPaginatedResponse
      • PosMenuItemDtoPaginatedResponseApiResponse
      • RateAdjustmentTemplateDtoPaginatedResponseApiResponse
      • RatePlanRefDto
      • RecentReservationsDto
      • ReservationBillingDto
      • ReservationCancellationDto
      • PropertyConfigurationDto
      • ReservationEventDtoPaginatedResponse
      • PropertyConfigurationDtoApiResponse
      • ReservationEventDtoPaginatedResponseApiResponse
      • ReservationSourceDto
      • ReservationStatusDto
      • ReservationDtoApiResponse
      • ReservationDtoListApiResponse
      • ReservationStatusDtoListApiResponse
      • ReservationDtoPaginatedResponse
      • ReservationStayStatusDto
      • ReservationDtoPaginatedResponseApiResponse
      • RoomAssignmentItemDto
      • ReservationBookingDto
      • RoomCheckInDto
      • RoomCheckOutDto
      • RoomDto
      • RoomDtoPaginatedResponse
      • RoomDtoPaginatedResponseApiResponse
      • ReservationEventDto
      • RoomInventoryUpdateRequestDto
      • RoomInventoryUpdateResponseDto
      • RoomInventoryUpdateResponseDtoApiResponse
      • RoomRateDto
      • ReservationDto
      • RoomRateDtoPaginatedResponse
      • RoomRateDtoPaginatedResponseApiResponse
      • ReservationRoomDto
      • RoomRateFailureDto
      • RoomRateItemDto
      • RoomRateUpdateRequestDto
      • RoomRateUpdateResponseDto
      • RoomRateUpdateResponseDtoApiResponse
      • ReservationGuestDto
      • RoomTypeDto
      • ReservationOccupancyDto
      • RoomTypeDtoPaginatedResponse
      • RoomTypeDtoPaginatedResponseApiResponse
      • RoomTypeRefDto
      • StaySpendDto
      • TemplateDateRangeDto
      • TitleRefDto
      • TravelAgentDto
      • RoomPerformanceComparisonDto
      • TravelAgentDtoPaginatedResponse
      • RoomPerformanceMetricsDto
      • TravelAgentDtoPaginatedResponseApiResponse
      • RoomPerformancePeriodDto
      • UpdateMasterRatesRequestDto
      • RoomPerformanceResponseDto
      • UpdateMasterRatesResultDto
      • RoomPerformanceResponseDtoApiResponse
      • UpdateMasterRatesResultDtoApiResponse
      • UpdateReservationRequestDto
      • UpdateReservationResponseDtoApiResponse
      • RoomTypePerformanceDto
      • UpdateReservationResponseDto
      • SpecialRequestsDto
  • MCP
    • Overview
    • Connect Your AI Assistant
  • Webhooks
    • Set Up and Edit Webhooks
    • Verify Webhook Signatures
    • List of Webhook Events
  1. Webhooks

Set Up and Edit Webhooks

How WinCloud webhooks work, what each request looks like, and how to start receiving them.

How webhooks work#

A webhook is a call from WinCloud to your server, made when data changes, so you do not have to keep asking the API whether anything is new.
1.
A reservation, rate, room or POS menu item changes in WinCloud.
2.
WinCloud sends an HTTP POST with the changed record to every endpoint subscribed to that event for that property.
3.
Your endpoint checks the signature, replies 2xx straight away, and processes the event afterwards.
Each event carries the record as it is after the change. For anything else you need, call the matching endpoint in the API reference. The events and their endpoints are listed in List of Webhook Events.

Set up a webhook#

Webhooks are set up for you by your RBS administrator. Send them:
DetailExample
Your endpoint URL. It must use HTTPShttps://partner.example.com/wincloud/webhooks
The events you wantreservations.changed, rates.changed
The properties you integrate withYour property IDs, for example international
You get back a signing secret for the subscription. You need it to check that each request really came from WinCloud; see Verify Webhook Signatures. Store it like a password, in a secrets manager and never in source control.
Your endpoint must:
accept POST requests over HTTPS
reply within 15 seconds
reply 2xx once it has accepted the event

Edit or remove a webhook#

To change the endpoint URL, add or remove events, replace the signing secret, or stop a webhook, ask your RBS administrator.

What each request contains#

Every delivery is an HTTP POST with a JSON body and these headers:
HeaderValue
Content-Typeapplication/json
X-RBS-Signaturet=<unix_seconds>,v1=<hex>. See Verify Webhook Signatures
X-RBS-Event-IdThe event id, the same as id in the body
X-RBS-Event-TypeThe event type, for example reservations.changed
X-RBS-Delivery-IdA new identifier for each delivery attempt
X-RBS-AttemptThe attempt number, starting at 1
The body is the same shape for every event. The record that changed is in data:
{
  "id": 4211,
  "type": "reservations.changed",
  "source": "WINCLOUD",
  "customerCode": "international",
  "customerName": "International Hotels",
  "locationCode": "01",
  "idempotencyKey": "international#...#10452#20261101144402000",
  "createdAt": "2026-11-01T09:14:05.512+00:00",
  "data": {}
}
FieldTypeDescription
idintegerUnique event id. Use it to spot duplicates
typestringThe event type
sourcestringThe system that produced the event
customerCodestringThe property ID, in lower case. It does not change, so use it to match events to a property
customerNamestringThe property's display name. It can change
locationCodestring or nullThe companyId within the property. null when the event applies to the whole property
idempotencyKeystringIdentifies the exact version of the record this event describes. Treat it as an opaque string; its format can change
createdAtstringWhen WinCloud recorded the event, in ISO 8601 with a UTC offset
dataobjectThe changed record. Its fields depend on type; see List of Webhook Events

Responses and retries#

Your endpoint repliesWinCloud
2xx within 15 secondsCounts the delivery as successful
408, 429 or any 5xx, or no reply within 15 seconds, or the connection failsTries again later
Anything else, including a redirect (3xx)Stops. Redirects are not followed, so give the final URL
A failed delivery is retried several more times within roughly the first 15 minutes, then after about 30 minutes, 1 hour, 2 hours and 4 hours. If every attempt fails, the event is not sent again.

Build your endpoint to handle#

Duplicates. The same event can arrive more than once. Save the id of each event you process and skip any you have seen. Do not use X-RBS-Delivery-Id for this; it changes on every attempt.
Events out of order. Events can arrive in a different order from the changes. Compare the last-updated time inside data with the record you already hold, and keep the newer one.
Missed events. If your endpoint was down for longer than the retry period, call the API for that period to catch up.
Slow processing. Reply 2xx as soon as the signature checks out, then do the work in the background, so you stay inside the 15 seconds.
IP allow-lists. If your firewall only accepts known addresses, ask the WinCloud Support Team for the addresses webhooks are sent from.
Modified at 2026-11-02 15:02:00
Previous
Connect Your AI Assistant
Next
Verify Webhook Signatures
Built with