Skip to main content

Event-based webhook flow


Introduction​

The webhook event-based flow for restaurant reservations and customer management allows integration between TheFork system and your CRM system. This integration enables real-time communication of events such as customer creation, customer update, reservation creation, and reservation update. This comprehensive documentation outlines the steps required to activate and utilize these features effectively.


Activation process​

To activate the webhook feature, follow these steps:

  1. Provide Endpoint: create a RESTful POST endpoint on your CRM system with a custom URL and a token.  
    Example: https://data.myrestaurant.com/api/thefork?token=NN8ul7c3wRE0hYP2XPOhyYDRQnyHFMJq
  2. Token Generation: generate a token of your choice to include in the endpoint URL.
  3. Inform TheFork: provide the generated endpoint URL with the token to TheFork system for configuration.

Webhook payload​

Upon activation, TheFork system will send payload data to your provided endpoint. The payload includes the following information:

  • entityType: identifies the type of entity that was created or updated (customer or reservation).
  • uuid: unique identifier (UUID) of the entity, necessary for retrieving the latest data from TheFork API.
  • eventType: indicates whether it is a new entity creation or an update (customerCreated, customerUpdated, reservationCreated, reservationUpdated).

Example:

{
  "entityType": "reservation",
  "uuid": "645aed28-67a5-4765-93f9-862c5697650c",
  "eventType": "reservationCreated"
}

Handling Webhook Events​

Upon receiving a webhook event, your CRM system should perform the following actions:

  1. Process Event: parse the received payload to extract relevant information such as entity type, UUID, and event type.
  2. Retrieve Latest Data: utilize the UUID provided in the payload to call TheFork API (GET /reservations or GET /customers) and fetch the latest data for the corresponding entity.
  3. Acknowledge Request: respond to the webhook event with a 200 HTTP status code and an empty JSON response to acknowledge successful reception.
{
  "data": {}
}

Error Handling​

In case of errors encountered during webhook event processing, your CRM system should handle them appropriately. TheFork system manages the following error scenarios:

  1. Restaurant Group Configuration Error (RESTAURANT_GROUP_NOT_READY):
  • Status code: 400
  • Error Identifier: RESTAURANT_GROUP_NOT_READY
  • Message: "The restaurant group needs to accept TheFork ERB in the tool"
  • Response Format:
{
  "error": "RESTAURANT_GROUP_NOT_READY",
  "message": "The restaurant group needs to accept TheFork ERB in the tool",
  "data": {}
}
  1. Rate Limit Exceeded (RATE_LIMIT):
  • Status code: 429
  • Error Identifier: RATE_LIMIT
  • Message: "You have reached the maximum number of requests per minute"
  • Response Format:
{
  "error": "RATE_LIMIT",
  "message": "You have reached the maximum number of requests per minute",
  "data": {}
}