Action links

If you send out your own notifications and emails to customers, you can generate one-time-use 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.

👍

Build vs. buy

Remember that you can always decide to rely on Timekit's default email notifications. However, if you are building a white label solution, action links are a great way to offer the same functionality in your own emails.

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:

# 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

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.

📘

Debugging 🛠

If you need to debug your JWT tokens, you can use this debugger to test everything manually.

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:

{
  "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:

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

This will generate a signature similar to this one:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJib29raW5nX2lkIjoiNGYxZGZkMWUtZDZhMS00Y2FiLTljN2YtOTk2ZTJiYzFhN2U1IiwiYWN0aW9uIjoiY2FuY2VsIn0.-_E0aKZA6ePnHzTnliYB52wexfTt74Ins00kwjThGiM

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