Introduction
Webhooks in Timerise API provide a powerful way to enable real-time interactions with external applications. When a specified event such as a status change or a new booking occurs, Timerise sends a notification to a predefined URL endpoint in your application.
Creating a Webhook for BOOKING_CREATE Event
To start listening for BOOKING_CREATE events, you need to set up a webhook in Timerise API.
CURL Example:
curl -X POST https://api.timerise.io/mutation \
-H "Content-Type: application/json" \
-d '{
"query": "mutation { webhookCreate(projectId: \"YourProjectID\", event: BOOKING_CREATE, url: \"https://yourapp.com/webhook\") { webhookId } }"
}'
Node.js Example:
const axios = require('axios');
axios.post('https://api.timerise.io/mutation', {
query: `mutation {
webhookCreate(projectId: "YourProjectID", event: BOOKING_CREATE, url: "https://yourapp.com/webhook") {
webhookId
}
}`
}).then(response => {
console.log("Webhook Created:", response.data);
}).catch(error => {
console.error(error);
});
Handling Notifications in Your Application
Upon receiving a notification from Timerise (containing the booking ID), your application can execute various actions on the booking.
Retrieve Booking Information
Use booking(bookingId: ID!) to fetch details of a specific booking.
Change Booking Status
Perform mutations like bookingAccept(bookingId: ID!) to change the status of a booking.
Deleting a Webhook
To remove an existing webhook, use the following examples:
CURL Example:
curl -X POST https://api.timerise.io/v1 \
-H "Content-Type: application/json" \
-d '{
"query": "mutation { webhookDelete(projectId: \"YourProjectID\", webhookId: \"YourWebhookID\") }"
}'
Node.js Example:
axios.post('https://api.timerise.io/v1, {
query: `mutation {
webhookDelete(projectId: "YourProjectID", webhookId: "YourWebhookID")
}`
}).then(response => {
console.log("Webhook Deleted:", response.data);
}).catch(error => {
console.error(error);
});
Tips and Best Practices
Webhook ID Storage: Save the ID of created webhooks for easy management later.
Error Handling: Implement robust error handling for cases where notifications are not properly delivered.
Security: Ensure secure communication between Timerise and your application.
Testing: Thoroughly test your webhook implementations to ensure they work as expected.
Practical Examples
This comprehensive guide provides practical examples of how to use webhooks in Timerise API for efficient interaction with external applications. The examples are demonstrated using both CURL and Node.js.
Retrieving Booking Details after Receiving BOOKING_CREATE Webhook
When your application receives a BOOKING_CREATE webhook, you can use the provided booking ID to fetch detailed information about the booking.
CURL Example:
curl -X POST https://api.timerise.io/v1 \
-H "Content-Type: application/json" \
-d '{
"query": "query { booking(bookingId: \"ReceivedBookingID\") { title, status, dateTimeFrom, dateTimeTo } }"
}'
Node.js Example:
const axios = require('axios');
axios.post('https://api.timerise.io/v1, {
query: `query {
booking(bookingId: "ReceivedBookingID") {
title
status
dateTimeFrom
dateTimeTo
}
}`
}).then(response => {
console.log("Booking Details:", response.data);
}).catch(error => {
console.error(error);
});
Changing Booking Status to ACCEPTED after Receiving BOOKING_UPDATE Webhook
Upon receiving a BOOKING_UPDATE webhook, you can update the status of the booking to ACCEPTED.
CURL Example:
curl -X POST https://api.timerise.io/v1 \
-H "Content-Type: application/json" \
-d '{
"query": "mutation { bookingAccept(projectId: \"YourProjectID\", bookingId: \"ReceivedBookingID\") { bookingId, status } }"
}'
Node.js Example:
const axios = require('axios');
axios.post('https://api.timerise.io/v1, {
query: `mutation {
bookingAccept(projectId: "YourProjectID", bookingId: "ReceivedBookingID") {
bookingId
status
}
}`
}).then(response => {
console.log("Booking Status Updated:", response.data);
}).catch(error => {
console.error(error);
});
Creating Stripe Payment Link after Receiving BOOKING_CREATE Webhook
Once your application receives a BOOKING_CREATE webhook, you can generate a Stripe payment link for the specific booking.
CURL Example:
curl -X POST https://api.timerise.io/v1 \
-H "Content-Type: application/json" \
-d '{
"query": "mutation { bookingPaymentLink(bookingId: \"ReceivedBookingID\", paymentProvider: STRIPE) { url } }"
}'
Node.js Example:
const axios = require('axios');
axios.post('https://api.timerise.io/v1, {
query: `mutation {
bookingPaymentLink(bookingId: "ReceivedBookingID", paymentProvider: STRIPE) {
url
}
}`
}).then(response => {
console.log("Stripe Payment Link:", response.data);
}).catch(error => {
console.error(error);
});
Conclusion
Using webhooks in Timerise API allows for efficient and dynamic interaction with your application. You can automate processes, respond to changes in real-time, and integrate Timerise with other systems in your organization. This guide provides a foundation to effectively utilize webhooks for enhancing your application's capabilities with Timerise API.