How to use webhook

Getting started

Webhook allows Jicoo to send POST requests to a specified URL when certain events occur.
Webhook schema

When a Webhook is configured, a signature secret is generated. It is strongly recommended to use this signature secret to verify that the request was sent from Jicoo.

In order to use Webhook, you must pre-subscribe to the Pro plan and create a webhook endpoint from the dashboard.
https://www.jicoo.com/dashboard/webhooks

Request

The Jicoo Webhook API requests the URL specified in the POST method.

Request headers

Webhook request headers from Jicoo always include the following keys.

{
    "content-type": "application/json",
    "Jicoo-Webhook-Signature": "Signature data"
}

It is recommended to use the Jicoo-Webhook-Signature header to verify that the POST request is a request sent by Jicoo. If there is no match, discard the request.

Verifying signatures

Validate events that Jicoo sends to Webhook endpoints.
By including a signature in the Jicoo-Webhook-Signature header of each event, Jicoo can sign Webhook events sent to the endpoint as needed. This allows you to verify that the event was sent by Jicoo. You will need to manually implement your own solution to verify the signature.

To enable signature verification, you must have previously obtained the endpoint's secret from the Webhook settings on the dashboard. Select the endpoint for which you want to retrieve the secret and click the Show button.

Jicoo generates a unique signature secret for each endpoint. Additionally, if multiple endpoints are used, a secret must be obtained for each endpoint whose signature is to be verified. After this configuration, Jicoo will start signing each webhook sent to the endpoint.

The Jicoo-Webhook-Signature header included in a signed event contains a timestamp and a signature. The timestamp is preceded by t= and each signature is preceded by a "scheme". The scheme begins with a v followed by an integer. Currently, the only valid signature scheme in the production environment is v1.

Jicoo-Webhook-Signature: t=1662520836,v1=85c11d0c60d680ab186996f934c7dcfe64da7d925f64e9b2e4d35d1fb73d6e5f

Jicoo generates signatures using a hash-based message authentication code (HMAC) with SHA-256.

Step 1: Extract the timestamp and signatures from the header

To get a list of elements, split the header using the , character as the delimiter. Then, separate each element using the = character as the delimiter to get the prefix-value pairs.

The value of the prefix t corresponds to the timestamp and v1 corresponds to the signature. All other elements can be discarded.

Step 2: Prepare the signed payload string

A string for signature verification is created by concatenating the following:

• The timestamp (string)
• The character .
• The JSON payload (The request body)

Step 3: Determine the expected signature

Calculate the HMAC using the SHA256 hash function. Uses the endpoint's signature secret as the key and the signature verification string as the message.

Step 4: Compare the signatures

1. compares the signature in the header with the expected signature.
2. If a match is found, calculate the difference between the current timestamp and the received timestamp and determine if the difference is within an acceptable range. To protect against timing attacks, a solution should be created to determine the acceptable range as a service and reject webhooks older than the acceptable range when they are received.

Webhook event types

Currently, there are event types sent by Jicoo Webhook.
event property

guest_booked

Webhook request generated when a reservation is created by a guest.

{
  "createdAt": "2020-11-23T17:51:19.000Z",
  "event": "guest_booked",
  "object": {
    "status": "open",
    "timeZone": "America/New_York",
    "startedAt": "2022-09-01T17:00:00.000Z",
    "endedAt": "2022-09-01T18:00:00.000Z",
    "createdAt": "2020-11-23T17:51:18.341Z",
    "updatedAt": "2020-11-23T17:51:18.341Z",
    "uid": "ACDADADASS",
    "eventTypeUid": "ACDASSS1ASS",
    "contact": {
      "email": "example@example.com",
      "name": "John Doe"
    },
    "answers": [{
      "question": "How did you find out?",
      "content": ["SNS", "DM"]
    }],
    "tracking": {
      "utm_campaign": "winter_campaign",
      "utm_source": "twitter",
      "utm_medium": "owned_media",
      "utm_content": "jicoo-how-to",
      "utm_term": "howto"
    }
  }
}

guest_rescheduled

Webhook request generated when a reservation date is changed by a guest.

{
  "createdAt": "2020-11-23T17:51:19.000Z",
  "event": "guest_rescheduled",
  "object": {
    "status": "open",
    "timeZone": "America/New_York",
    "startedAt": "2022-09-01T17:00:00.000Z",
    "endedAt": "2022-09-01T18:00:00.000Z",
    "createdAt": "2020-11-23T17:51:18.341Z",
    "updatedAt": "2020-11-23T17:51:18.341Z",
    "uid": "ACDADADASS",
    "eventTypeUid": "ACDASSS1ASS",
    "contact": {
      "email": "example@example.com",
      "name": "John Doe"
    },
    "answers": [{
      "question": "How did you find out?",
      "content": ["SNS", "DM"]
    }],
    "tracking": {
      "utm_campaign": "winter_campaign",
      "utm_source": "twitter",
      "utm_medium": "owned_media",
      "utm_content": "jicoo-how-to",
      "utm_term": "howto"
    }
  }
}

host_rescheduled

A webhook request generated when the reservation dates are changed by the host.

{
  "createdAt": "2020-11-23T17:51:19.000Z",
  "event": "host_rescheduled",
  "object": {
    "status": "open",
    "timeZone": "America/New_York",
    "startedAt": "2022-09-01T17:00:00.000Z",
    "endedAt": "2022-09-01T18:00:00.000Z",
    "createdAt": "2020-11-23T17:51:18.341Z",
    "updatedAt": "2020-11-23T17:51:18.341Z",
    "uid": "ACDADADASS",
    "eventTypeUid": "ACDASSS1ASS",
    "contact": {
      "email": "example@example.com",
      "name": "John Doe"
    },
    "answers": [{
      "question": "How did you find out?",
      "content": ["SNS", "DM"]
    }],
    "tracking": {
      "utm_campaign": "winter_campaign",
      "utm_source": "twitter",
      "utm_medium": "owned_media",
      "utm_content": "jicoo-how-to",
      "utm_term": "howto"
    }
  }
}

guest_cancelled

Webhook request generated when a reservation is cancelled by a guest.

{
  "createdAt": "2020-11-23T17:51:19.000000Z",
  "event": "guest_cancelled",
  "object": {
    "status": "cancel",
    "timeZone": "America/New_York",
    "startedAt": "2022-09-01T17:00:00.000Z",
    "endedAt": "2022-09-01T18:00:00.000Z",
    "createdAt": "2020-11-23T17:51:18.341657Z",
    "updatedAt": "2020-11-23T17:51:18.341657Z",
    "uid": "ACDADADASS",
    "eventTypeUid": "ACDASSS1ASS",
    "cancelReason": "Another meeting scheduled",
    "cancelledAt": "2022-09-01T17:00:00.000Z",
    "cancelledBy": "guest",
    "contact": {
      "email": "example@example.com",
      "name": "John Doe"
    },
    "answers": [{
      "question": "How did you find out?",
      "content": ["SNS", "DM"]
    }],
    "tracking": {
      "utm_campaign": "winter_campaign",
      "utm_source": "twitter",
      "utm_medium": "owned_media",
      "utm_content": "jicoo-how-to",
      "utm_term": "howto"
    }
  }
}

host_cancelled

Webhook request generated when a reservation is cancelled by a host.

{
  "createdAt": "2020-11-23T17:51:19.000000Z",
  "event": "host_cancelled",
  "object": {
    "status": "cancel",
    "timeZone": "America/New_York",
    "startedAt": "2022-09-01T17:00:00.000Z",
    "endedAt": "2022-09-01T18:00:00.000Z",
    "createdAt": "2020-11-23T17:51:18.341Z",
    "updatedAt": "2020-11-23T17:51:18.341Z",
    "uid": "ACDADADASS",
    "eventTypeUid": "ACDASSS1ASS",
    "cancelReason": "Another meeting scheduled",
    "cancelledAt": "2022-09-01T17:00:00.000Z",
    "cancelledBy": "host",
    "contact": {
      "email": "example@example.com",
      "name": "John Doe"
    },
    "answers": [{
      "question": "How did you find out?",
      "content": ["SNS", "DM"]
    }],
    "tracking": {
      "utm_campaign": "winter_campaign",
      "utm_source": "twitter",
      "utm_medium": "owned_media",
      "utm_content": "jicoo-how-to",
      "utm_term": "howto"
    }
  }
}

How to track event conversions

If you have a Jicoo account, you can add the UTM (Urchin tracking module) parameter to the link on the booking page to
You can track with webhooks by adding a UTM (Urchin tracking module) parameter to the link on the booking page. Please follow the steps below to build the link for tracking.

1.First define which UTM code is to be added to the link. You may use any of the following codes

• UTM Source
  This is where you label which site the booked meeting came from. For example, if you are running a campaign on Twitter, add "utm_source=twitter" to the link.

• UTM Medium
  This is where you label where the link came from. For example, if you used the link on a social networking site, you could add "utm_medium=social" to the link.

• UTM Campaign
  Here you can name your campaign. If you have many links in many different places, this UTM code allows you to connect each one. For example, if you have a summer campaign, you can add "utm_campaign=summer%20promotion" to the link.

• UTM Content
  If you have multiple links to the same reservation page, you can use UTM Content to see where guests are clicking to make a reservation. For example, you could use "utm_content=header" for a link in the header of your website and "utm_content=footer" for a link in the footer of your website.

• UTM Term
  This is a way to track specific keywords. For example, if you pay for an ad to rank for the keyword "booking", you would need to add "utm_term=booking" to your link.

2.Once you have determined the UTM code to use, add a "?" after the booking page link. and add the UTM codes separated by '&'.

(e.g. utm_medium=social&utm_source=facebook) Use "%20" to add a space in the code (e.g. utm_campaign=summer%20promotion). The link will look like this.

https://www.jicoo.com/{Event page URL}?utm_medium=social&utm_source=twitter&utm_campaign=summer%20promotion

The above parameters are set in the webhook POST request tracking.

"tracking": {
  "utm_campaign": "summer promotion",
  "utm_source": "twitter",
  "utm_medium": "social",
  "utm_content": null,
  "utm_term": null
}

Response

When your system receives a request from the Jicoo Webhook, it should return a response with status code 200.

A Webhook is considered to have failed to send or receive in the following cases

• Endpoint returns HTTP response with status code 3xx, 4xx or 5xx
• Connection to the system times out (default timeout value is 15 seconds)
• Unable to establish a secure SSL connection to the system

If the transmission fails, retry processing is performed twice with an interval of 10 seconds.

• 1st time: Requested immediately upon event occurrence
• Second: If the first request meets the above conditions, retry after 10 seconds.
• Third time: If the second request meets the above conditions, resubmit after 10 seconds (if the third request fails, no retry is performed).

Notes

• Notification of reservations created in a private project will not be notified if the webhook creator is not a participant in that project.