Action links

If you send out your own notifications and emails to customers, you can generate action links that can update a booking's state when someone clicks it. Links are crytographically limited to 1 booking and 1 action only, so they are safe to send out to your users.

Action links are not one-time use and do not expire. A link keeps working for as long as the booking's current state allows its action; once the booking has moved on (for example, it has been cancelled), the link is rejected.

A cancel action link looks like this:

https://api.timekit.io/v2/bookings/{bookingId}/external_action/{action}?signature={JWT token}&redirect=https%3A%2F%2Fexample.com%2Freschedule

It consists of 3 dynamic parts:

• Action: The name of the booking action, ie. confirm, decline or cancel
• Signature: A JWT token that assures validity of the request
• Redirect (optional): A URL to redirect the user after the action has been updated (ie. a thank you page, a rescheduling page etc.)

Retrieving pre-generated action links

If you're looking to use action links for customer actions on bookings, we can generate them for you so you can use them right away without the hassle.

When retrieving bookings or a single booking, add the following dynamic includes to your request: customer_action_links

Here's a full example:

curl
# Request example
# [GET] /bookings with dynamic include
curl --request GET \
     --user :live_api_key_7nzvc7wsBQQISLeFSVhROys9V1bUJ1z7 \
     https://api.timekit.io/v2/bookings?include=customer_action_links

If the following actions are logically available on the given bookings (decided based on their graph and current state), the action links for them are returned:

• cancel_by_customer
• reschedule_by_customer

When cancel_by_customer is returned, the response also has a cancel_by_customer_page key: a link to the Timekit-hosted cancellation page for the booking.

A reschedule or reschedule_by_customer link does not change the booking's state by itself. It redirects the customer to the project's rescheduling URL (or to the project's hosted booking page if none is set), where they pick a new time.

Generating action link signatures

The JWT token passed to the signature query param of the URL is used to verify the validity and credibility of the action link.

If you are new to JWT, please have a look at the official website.

The JWT token used in Timekit action links is using the HS256 algorithm and the secret is your app API-Key. The JSON payload consists of a booking_id and the name of the action. It should look like this:

json
{
  "booking_id": "95b8c686-48b3-47af-b966-d64a6f726165",
  "action": "cancel"
}

Usually you will use a library to generate the JWT token, depending on which programming language you are using. Algorithmically, generating the token looks something like this:

text
HMACSHA256(
    base64UrlEncode(header) + "." +
    base64UrlEncode(payload),
    'live_api_key_7nzvc7wsBQQISLeFSVhROys9V1bUJ1z7'
);

This will generate a signature similar to this one:

text
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJib29raW5nX2lkIjoiNGYxZGZkMWUtZDZhMS00Y2FiLTljN2YtOTk2ZTJiYzFhN2U1IiwiYWN0aW9uIjoiY2FuY2VsIn0.-_E0aKZA6ePnHzTnliYB52wexfTt74Ins00kwjThGiM

👏 You are now ready to put together your action link!