General Webhooks

General Webhooks

General Webhooks provide a streamlined way to receive event notifications about various Mews entities. Each Webhook message corresponds to a specific enterprise integration, identifiable via the EnterpriseId and IntegrationId fields in the request body. These identifiers allow you to track events across all enterprises or properties connected to your integration.

Key features

• Unified event delivery – Each message encapsulates all events related to the entities you’ve subscribed to that occur simultaneously. For example, subscribing to Service Order events (which include reservations as a subtype) may result in a Webhook containing multiple ServiceOrderUpdated events, each corresponding to a different reservation.

• Event structure – Each event within a message specifies the event type and includes the unique identifier of the associated entity, e.g. CustomerAdded events include a CustomerId. To retrieve detailed information about an entity, use the relevant API Operation along with the entity’s unique identifier. For instance, for a CustomerAdded event, call Get all customers with the provided CustomerId.

• Efficient integration - Receive notifications for all subscribed enterprises or properties in a single payload, minimizing the need for multiple requests or real-time polling. Leverage EnterpriseId and IntegrationId to manage and filter event data effectively.

Implementation

To implement General Webhooks:

1. Define the entities and event types you are interested in via your Webhook subscription.
2. Use EnterpriseId and IntegrationId to differentiate messages across multiple enterprises or properties.
3. Fetch additional details about entities as needed by using the appropriate API Operations.

Supported events

Entity	Event	Description
Service Order	ServiceOrderUpdated	Event triggered when a service order is updated
Resource	ResourceUpdated	Event triggered when a resource is updated
Message	MessageAdded	Event triggered when a new message is added
Resource block	ResourceBlockUpdated	Event triggered when a resource block is updated
Customer	CustomerAdded	Event triggered when a customer is added
Customer	CustomerUpdated	Event triggered when a customer is updated
Payment	PaymentUpdated	Event triggered when a payment is updated

Terminology

A Service Order is an order made against a Service. A Service Order made against a Bookable Service is called a Reservation. In fact only Reservations are currently supported, however this may be extended in future. A Resource can be a bookable space, an object or even the services of a person. Resource normally implies a space, but again this may be extended in future. For a full description of all the terms used, see the Mews Glossary for Open API users.

Added vs Updated events

In the context of General Webhooks, the terms Added and Updated describe different types of changes to an entity:

• Updated – This indicates any change to an entity, including modifications to its fields or properties; it also encompasses the creation of a new entity, as creating an entity is considered a change to its lifecycle state.
• Added – This specifically refers to the initial creation of an entity at the start of its lifecycle; it represents a subset of Updated events, as every Added event is inherently also an Updated event.

Important considerations

Asynchronous processing

When processing Webhook messages, it is crucial for the server to respond quickly to the Webhook request, otherwise the request may time out and will be retried (see Do you attempt to resend failed Webhook messages?). If you need to perform additional operations, such as making external API calls, make sure to process incoming webhook messages asynchronously. You can, for example, store the incoming Webhook message in a queue and respond to the Webhook request immediately.

CustomerAdded and CustomerUpdated events

When you subscribe to events for entities like Customers, a newly created entity generates both a CustomerAdded event and a CustomerUpdated event. These events will have the same CustomerId and will often appear within the same Webhook message.

To avoid redundant API calls, ensure that you process each entity only once. For example, when you receive both a CustomerAdded and a CustomerUpdated event for the same CustomerId, call Get all customers only once to retrieve the entity details.

Request body

{
    "EnterpriseId": "851df8c8-90f2-4c4a-8e01-a4fc46b25178",
    "IntegrationId": "c8bee838-7fb1-4f4e-8fac-ac87008b2f90",
    "Events": [
        {
            "Discriminator": "ServiceOrderUpdated",
            "Value": {
                "Id": "bfee2c44-1f84-4326-a862-5289598f6e2d"
            }
        },
        {
            "Discriminator": "ResourceUpdated",
            "Value": {
                "Id": "7cccbdc6-73cf-4cd4-8056-6fd00f4d9699"
            }
        },
        {
            "Discriminator": "MessageAdded",
            "Value": {
                "Id": "4bfe4675-98a9-4428-9ea9-ae5300dbaa93"
            }
        },
        {
            "Discriminator": "CustomerAdded",
            "Value": {
                "Id": "c2f1d888-232e-49eb-87ac-5f75363af13b"
            }
        },
        {
            "Discriminator": "CustomerUpdated",
            "Value": {
                "Id": "b3ce0fd7-a715-4bfc-969e-ef7a4822963c"
            }
        },
        {
            "Discriminator": "PaymentUpdated",
            "Value": {
                "Id": "a41e2d45-71bc-49b4-9a05-a3ac5f75735c"
            }
        }
    ]
}

Property	Type	Contract	Description
EnterpriseId	string	required	Unique identifier of the Enterprise to which the events belong.
IntegrationId	string	required	Unique identifier of the Integration to which the events belong.
Events	array of Event	required	The set of events that have occurred.

Event

Property	Type	Contract	Description
Discriminator	string Event discriminator	required	The type of event.
Value	object	required	The structure of the object depends on Event discriminator.

Event discriminator

Discriminator	Description	Value	Fetch operation
ServiceOrderUpdated	A Reservation or other Service Order was updated.	Entity updated data	Get all reservations
ResourceUpdated	A Resource (for example a guest room or other space) was updated.	Entity updated data	Get all resources
MessageAdded	A Message was added.	Entity updated data	Get all messages
ResourceBlockUpdated	A Resource block was updated.	Entity updated data	Get all resource blocks
CustomerAdded	A Customer was added.	Entity updated data	Get all customers
CustomerUpdated	A Customer was updated.	Entity updated data	Get all customers
PaymentUpdated	A Payment was updated.	Entity updated data	Get all payments

Entity updated data

Property	Type	Contract	Description
Id	string	required	Unique identifier of the updated/added entity. To fetch entity data use the related operation per Event discriminator.