What is a webhook?
You use webhooks to be notified about changes that happens to a booking. If there is any changes to a booking you can tell Timekit that you want to be notified about that change.
When to use webhooks?
Webhooks are great when you want to control the customer experience and flow by implementing other services or processes in your customer experience. For example if you have payments as part of your service setup.
You can hook into any state change in a booking on Timekit, so if you want to be notified when a booking is created, confirmed or cancelled by customer you should use webhooks.
Lets say you want to post to Slack every time you get a new booking for your project "Sales Demo", you can setup a webhook on Timekit to notify Zapier and you will tell Zapier to post something in Slack.
We have an article about setting up Timekit + Zapier here: http://help.timekit.io/working-with-the-api/send-custom-emails-and-other-notifications-with-webhooks-via-zapier
An example
Let's look over an example webhook from Timekit. This is the data that you get from Timekit about a single booking.
This data contains info about the booking (current state, created_at, etc), the customer (name, email etc), the event (start, end etc)
{
"id": "b3c99d95-6a46-4957-b30e-bfc929efabc3",
"state": "confirmed",
"graph": "instant",
"completed": false,
"created_at": "2017-12-05T10:13:17+0000",
"updated_at": "2017-12-05T10:13:18+0000",
"customers": [{
"id": "de64b2f7-cdbd-4929-94e8-5813e5a44367",
"name": "Marty McFly",
"email": "mcfly@timekit.io",
"phone": "",
"voip": "",
"timezone": "America/Los_Angeles",
"meta": "{}"
}],
"event": {
"id": "18b9d750-7ca7-4275-afed-15f7a6a3c54b",
"what": "Doc. Emmett Brown x Marty McFly",
"where": "TBD",
"description": "Comment: If my calculations are correct, when this baby hits 88 miles per hour...",
"rsvp": "accepted",
"allDay": false,
"start": "2017-12-05T14:00:00+0000",
"end": "2017-12-05T15:00:00+0000",
"created_at": "2017-12-05T10:13:17+0000",
"updated_at": "2017-12-05T10:13:24+0000"
},
"calendar": {
"id": "f30c9c39-317c-4a28-915e-66a0abeabf09",
"provider_id": "doc@timekit.io",
"provider_access": "owner",
"provider_primary": true,
"provider_sync": true,
"name": "doc@timekit.io",
"description": null,
"foregroundcolor": "#1d1d1d",
"backgroundcolor": "#4986e7",
"created_at": "2015-05-12T03:49:11+0000",
"updated_at": "2017-12-05T10:13:24+0000",
"provider": "google"
},
"attributes": {
"customer": {
"comment": "If my calculations are correct, when this baby hits 88 miles per hour...",
"email": "mcfly@timekit.io",
"name": "Marty McFly",
"timezone": "Europe\/Madrid"
},
"event": {
"calendar_id": "f30c9c39-317c-4a28-915e-66a0abeabf09",
"description": "Comment: If my calculations are correct, when this baby hits 88 miles per hour...",
"end": "2017-12-05T16:00:00+01:00",
"invite": true,
"my_rsvp": "accepted",
"participants": ["mcfly@timekit.io"],
"start": "2017-12-05T15:00:00+01:00",
"sync_provider": true,
"what": "Doc. Emmett Brown x Marty McFly",
"where": "Hill Valley"
},
"event_info": {
"calendar_id": "f30c9c39-317c-4a28-915e-66a0abeabf09",
"description": "Comment: If my calculations are correct, when this baby hits 88 miles per hour...",
"end": "2017-12-05T15:00:00+0000",
"participants": ["doc@timekit.io"],
"start": "2017-12-05T14:00:00+0000",
"what": "Doc. Emmett Brown x Marty McFly",
"where": "Hill Valley"
}
},
"user": {
"id": "14ac45d1-5e38-4d1c-9cb9-4fcaa447fa97",
"first_name": "Doc. Emmett",
"last_name": "Brown",
"name": "Doc. Emmett Brown",
"email": "doc@timekit.io",
"image": "https:\/\/lh5.googleusercontent.com\/-9gtmiFGk5Q4\/AAAAAAAAAAI\/AAAAAAAAABk\/-qnPdiM7I2M\/photo.jpg",
"timezone": "America/Los_Angeles",
"created_at": "2015-05-12T03:48:59+0000",
"updated_at": "2017-07-05T16:19:45+0000"
}
}
Best practices
When you receive a webhook you need to respond with a 200, 201 or 204 HTTP status code to acknowledge that you have successfully received the webhook. If you dont respond with a 2xx we will try again 3 times and after that the webhook will be recorded as failed.
We are working on the ability to replay webhooks via the Admin if they have failed.
Next steps
Read this example on how to setup Timekit + Zapier:
http://help.timekit.io/working-with-the-api/send-custom-emails-and-other-notifications-with-webhooks-via-zapier
and then go set up webhooks for your own app.