Chapter 1

Getting started

Identify the events you want to subscribe to

In order to get started with the Matchi webhook, you need to identify the events that you want to subscribe to. You can use webhooks to receive notifications on events that happen in Matchi. This can be useful if you want to keep your system in sync with Matchi.

For example, you can use webhooks to:

  • Getting notified when a booking has been created or cancelled.

For more information on the events that can be subscribed to and the data that is sent with the event, see the events.

Create a webhook endpoint

You need to create a webhook endpoint on your server where the webhook events will be sent. The webhook endpoint is a URL that Matchi will send the webhook events to.

  • The endpoint must be able to handle HTTP POST requests. The events are pushed to the endpoint as HTTP POST
  • The endpoint must be able to handle the JSON data that is sent with the webhook event.
  • The endpoint must be with tls/ssl 1.2 or higher and have a valid certificate.
  • The endpoint should respond with a 2xx status code to indicate that the event was received successfully.
  • The endpoint should respond with a 4xx or 5xx status code to indicate that the event was not received successfully. The Matchi webhook will retry up to X amount of times sending the event if the endpoint responds with a 4xx or 5xx status code.
  • The endpoint must be able to handle duplicate events, the Matchi webhook only promises at-least-once delivery.
  • The endpoint must be able to handle the events in a timely manner, the Matchi webhook will retry sending the event if the endpoint does not respond within a certain time frame. The Matchi timeout is 10 seconds.

Test the webhook endpoint

Before you register the webhook subscription, you should test the webhook endpoint to ensure that it is working correctly. This could be done by creating a test server that pushes a test event to the webhook endpoint. This could be done with a tool like ngrok or writing a simple test server in your programming language of choice.

See the events for more information on the data that is sent with the event.

Register the webhook subscription

To get started with the Matchi webhook you need to create a subscription this is done by contacting Matchi support.

Secure the webhook endpoint

It is important to secure the webhook endpoint to ensure that the webhook event is from Matchi and not from a malicious source. For more information on how to verify the webhook event, see the security.