Chapter 3

Events

Introduction

All events are sent as a POST request to the webhook url. The message is sent as a JSON object in the body of the request. The content type of the request is application/json. All event data is built around the detail-type field.

The detail-type field is used to identify the type of event. The data for the event is stored in the detail field. The detail field is an object, and its structure varies based on the type of event. As a JSON object, its structure depends on the specified detail-type.

The definitions of each events data could be found in the specific event documentation pages, each event data structure is defined in a JSON schema.

Example event

{
    "detail-type": "BookingCreatedV1",
    "id": "3f1c2e9a-7b4d-4c8e-9a2f-1d5e6b7c8a90",
    "timestamp": "2024-05-22T09:00:00Z",
    "detail": {
        "players": [
            {
                "userId": "550e8400-e29b-41d4-a716-446655440000",
                "email": "john.doe@example.com",
                "isCustomer": false
            }
        ],
        "owner": {
            "customerId": "CUST123456",
            "userId": "550e8400-e29b-41d4-a716-446655440000",
            "firstName": "John",
            "lastName": "Doe",
            "email": "john.doe@example.com",
            "address": "123 Main St",
            "city": "Anytown",
            "zipcode": "12345",
            "country": "USA",
            "nationality": "American",
            "cellphone": "+1234567890",
            "telephone": "+0987654321",
            "dateOfBirth": "1980-01-01",
            "gender": "MALE",
            "isOrganization": false,
            "doNotEmail": false,
            "registrationDate": "2023-07-04T10:00:00+02:00"
        },
        "booking": {
            "bookingId": "1234555",
            "startTime": "2024-07-04T10:00:00+02:00",
            "endTime": "2024-07-04T11:00:00+02:00",
            "courtId": "C001",
            "courtName": "Main Court",
            "accessCode": "ACCESS1234",
            "splitPayment": true
        },
        "facility": {
            "facilityId": "2344123",
            "facilityName": "Matchi Tennis Club"
        }
    }
}

Event structure

All events are sent as a JSON object in the body of the request. With a envelope structure that are the same for all events. The envelope contains metadata for the event e.i id, detail-type, timestamp, and the event data. The event data is stored in the detail field.

Envelope

Field	Type	Description
id	string	A UUID that identifies the event. This is useful for tracking the event and for debugging purposes and checking for duplicates.
detail-type	string	`Detail-type` is used to identify the type of event. The data for the event is stored in the `detail` field. This field is an object, and its structure varies based on the type of event. As a JSON object, its structure depends on the specified `detail-type`.
detail	object	The data for the event. See sub-pages for the specific event data structure.
timestamp	string	The time the event was generated. The time is in RFC 3339 format.

Example envelope

{
    "id": "3f1c2e9a-7b4d-4c8e-9a2f-1d5e6b7c8a90",
    "detail-type": "BookingCreatedV1",
    "timestamp": "2024-05-22T09:00:00Z",
    "detail": {}
}

Detail-types

The following detail-types are available:

Detail-type	Description	Page
ActivityOccasionCancelledV1	Event triggered when an activity occasion is cancelled.	Activity Occasion Cancelled V1
ActivityOccasionParticipantJoinedV1	Event triggered when a participant joins an activity occasion.	Activity Occasion Participant Joined V1
ActivityOccasionParticipantLeftV1	Event triggered when a participant leaves an activity occasion.	Activity Occasion Participant Left V1
ActivityOccasionUpdatedV1	Event triggered when an activity occasion is updated.	Activity Occasion Updated V1
BookingCancelledV2	Event triggered when a booking is cancelled.	Booking Cancelled V2
BookingCreatedV2	Event triggered when a booking is created.	Booking Created V2
BookingMovedV2	Event triggered when a booking is moved.	Booking Moved V2
BookingCancelledV1	Deprecated, use BookingCancelledV2. Event triggered when a booking is cancelled.	Booking Cancelled V1
BookingCreatedV1	Deprecated, use BookingCreatedV2. Event triggered when a booking is created.	Booking Created V1
BookingMovedV1	Deprecated, use BookingMovedV2. Event triggered when a booking is moved.	Booking Moved V1
CustomerCreatedV1	Event triggered when a customer is created at facility.	Customer Created V1
CustomerDeletedV1	Event triggered when a customer is deleted at facility.	Customer Deleted V1
CustomerUpdatedV1	Event triggered when a customer is updated at facility.	Customer Updated V1

Event Data

The event data is stored in the detail field. The structure of the detail field varies based on the type of event. The structure of the detail field is defined in a JSON schema.

For more information about each of the events data structure, visit the specific event documentation page.

JSON Schema for Events

All Matchi Webhook events are based on a JSON schema. The JSON schema defines the structure of the event data. The JSON schema ensures that the event data is consistent and valid. Our JSON schemas follow the 2020-12 specification.

Note: The JSON schema for each event could be found at the top of the event documentation.

For more information about JSON Schema, visit the official JSON Schema website.