Skip to content

Commit

Permalink
Reorganized the webhook section, and added documentation for the tran…
Browse files Browse the repository at this point in the history 
…saction webhook
  • Loading branch information
Kevin Jackson committed Dec 21, 2016
1 parent 556a816 commit e93873e
Show file tree
Hide file tree
Showing 10 changed files with 232 additions and 125 deletions.
0 docs/examples/response/notification.json → docs/examples/response/webhook-booking.json
View file
File renamed without changes.
0 docs/examples/response/notification.xml → docs/examples/response/webhook-booking.xml
View file
File renamed without changes.
17 changes: 17 additions & 0 deletions docs/examples/response/webhook-payment.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
{
"version": "3.11.0.0",
"host": "your-company.checkfront.com",
"type": "transaction",
"action": "insert",
"transaction": {
"transaction_id": "TEST1482283550",
"date": 1582283550,
"status": "PAID",
"amount": "27.00",
"gateway_id": "TestPayment",
"payment_mask": "1111",
"payment_type": "Visa",
"payment_customer": "Testy McTestface",
"booking_id": "LULZ-080916"
}
}
16 changes: 16 additions & 0 deletions docs/examples/response/webhook-payment.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<?xml version="1.0" encoding="utf-8"?>
<checkfront-notify version="3.11.0.0" host="your-website.checkfront.com">
<type>transaction</type>
<action>insert</action>
<transaction>
<transaction_id>TEST1482284175</transaction_id>
<date>1482284175</date>
<status>PAID</status>
<amount>27.00</amount>
<gateway_id>TestPayment</gateway_id>
<payment_mask>1111</payment_mask>
<payment_type>Visa</payment_type>
<payment_customer>Testy McTestface</payment_customer>
<booking_id>LULZ-080916</booking_id>
</transaction>
</checkfront-notify>
136 changes: 11 additions & 125 deletions docs/ref/notifications.rst
View file
Original file line number Diff line number Diff line change
@@ -1,134 +1,20 @@
Webhooks
========

Your Checkfront account is capable of directly POSTing details of new or modified bookings to your SSL-secured server endpoint.
Your Checkfront account is capable of directly POSTing details of new or modified bookings, items,
item events, and transactions to your SSL-secured server endpoint.

Notifications are sent over a standard **HTTPS POST** request in the form of a **JSON**, **XML**, or **x-www-form-urlencoded** formatted booking object containing various particulars on a booking, and can be triggered to send on one or more status changes as defined by you in the setup process.
Notifications are sent over a standard **HTTPS POST** request as **JSON**, **XML**, or **x-www-form-urlencoded** data.

Your server **must** respond with an **HTTP 200** class status code immediately upon receipt. If your server does not indicate a successful response in a timely manner, after 5 consecutive failed delivery attempts, your webhook will be automatically disabled.
Your server **must** respond with an **HTTP 200** class status code immediately upon receipt.
If your server does not indicate a successful response in a timely manner,
after 5 consecutive failed delivery attempts, your webhook will be automatically disabled.

Webhook setup can be found in the **Manage > Developer** section of your Checkfront account under the "**Webhooks**" tab.

Booking Notification Data
^^^^^^^^^^^^^^^^^^^^^^^^^
.. toctree::
:caption: Webhook Events
:glob:
:maxdepth: 1

A **JSON**, **XML**, or **x-www-form-urlencoded** object containing the following export fields can be found in directly in the **raw body** of the POST request to your server:

booking
-------

+---------------------------+------------------+----------------------------------------------------------------------------+
| Field | Type | Description |
+===========================+==================+============================================================================+
| **status** | *string* | The current status code of the booking. |
+---------------------------+------------------+----------------------------------------------------------------------------+
| **code** | *string* | A unique booking code used to refer to the booking. |
+---------------------------+------------------+----------------------------------------------------------------------------+
| **created_date** | *timestamp* | The date on which the booking was created. |
+---------------------------+------------------+----------------------------------------------------------------------------+
| **staff_id** | *integer* | Account ID of the staff account used to create the booking. |
+---------------------------+------------------+----------------------------------------------------------------------------+
| **source_ip** | *string* | The IP address used to create the booking. |
+---------------------------+------------------+----------------------------------------------------------------------------+
| **start_date** | *timestamp* | The start date/time of the booking, based on order items. |
+---------------------------+------------------+----------------------------------------------------------------------------+
| **end_date** | *timestamp* | The end date/time of the booking, based on order items. |
+---------------------------+------------------+----------------------------------------------------------------------------+
| **customer** | *array* | Customer details attached to the booking. See :ref:`note-booking-customer`|
| | | below. |
+---------------------------+------------------+----------------------------------------------------------------------------+
| **meta** | *array* | A set of fields containing your custom parameters and other info. |
+---------------------------+------------------+----------------------------------------------------------------------------+
| **order** | *array* | Details on booking items and payment. See :ref:`note-booking-order` below.|
+---------------------------+------------------+----------------------------------------------------------------------------+

.. _note-booking-customer:

booking.customer
~~~~~~~~~~~~~~~~

+---------------------------+------------------+----------------------------------------------------------------------------+
| Field | Type | Description |
+===========================+==================+============================================================================+
| **name** | *string* | The customer's full name. |
+---------------------------+------------------+----------------------------------------------------------------------------+
| **email** | *string* | The customer's email address. |
+---------------------------+------------------+----------------------------------------------------------------------------+
| **address** | *string* | The customer's street address. |
+---------------------------+------------------+----------------------------------------------------------------------------+
| **region** | *string* | The customer's province or state. |
+---------------------------+------------------+----------------------------------------------------------------------------+
| **country** | *string* | The customer's country of residence. |
+---------------------------+------------------+----------------------------------------------------------------------------+
| **postal_zip** | *string* | The customer's postal or zip code. |
+---------------------------+------------------+----------------------------------------------------------------------------+
| **phone** | *string* | The customer's phone number. |
+---------------------------+------------------+----------------------------------------------------------------------------+

.. _note-booking-order:

booking.order
~~~~~~~~~~~~~

+---------------------------+------------------+----------------------------------------------------------------------------+
| Field | Type | Description |
+===========================+==================+============================================================================+
| **sub_total** | *float* | The sub-total of all charges added to the order. |
+---------------------------+------------------+----------------------------------------------------------------------------+
| **paid_total** | *float* | The total amount the customer has paid on the order. |
+---------------------------+------------------+----------------------------------------------------------------------------+
| **total** | *float* | The total of all charges and taxes added to the order. |
+---------------------------+------------------+----------------------------------------------------------------------------+
| **tax_total** | *float* | The sum of all taxes applied to the order. |
+---------------------------+------------------+----------------------------------------------------------------------------+
| **taxes** | *array* | Individual taxes that have been applied to the order, their names, and |
| | | amounts. |
+---------------------------+------------------+----------------------------------------------------------------------------+
| **discount** | *float* | The amount that has been discounted from the order total (if applicable). |
+---------------------------+------------------+----------------------------------------------------------------------------+
| **items** | *array* | Details on items included in the order. |
| | | See :ref:`note-booking-order-items` below. |
+---------------------------+------------------+----------------------------------------------------------------------------+

.. _note-booking-order-items:

booking.order.items.item
~~~~~~~~~~~~~~~~~~~~~~~~
An entry for *each* item in the booking exists will contain following fields:

+---------------------------+------------------+------------------------------------------------------------------------+
| Field | Type | Description |
+===========================+==================+========================================================================+
| **start_date** | *timestamp* | The start date of the booking item. |
+---------------------------+------------------+------------------------------------------------------------------------+
| **end_date** | *timestamp* | The end date of the booking item. |
+---------------------------+------------------+------------------------------------------------------------------------+
| **sku** | *string* | The unique stock keeping unit of the item. |
+---------------------------+------------------+------------------------------------------------------------------------+
| **slip** | *string* | The booking slip attached to the item. |
+---------------------------+------------------+------------------------------------------------------------------------+
| **package** | *integer* | The package the item belongs to (if applicable). |
+---------------------------+------------------+------------------------------------------------------------------------+
| **status** | *string* | The booking status of the item. |
+---------------------------+------------------+------------------------------------------------------------------------+
| **total** | *float* | The total price of the booking item. |
+---------------------------+------------------+------------------------------------------------------------------------+
| **tax_total** | *float* | The sum of taxes applied to this item. |
+---------------------------+------------------+------------------------------------------------------------------------+
| **qty** | *integer* | The quantity of this item in the booking. |
+---------------------------+------------------+------------------------------------------------------------------------+


Sample Notification
^^^^^^^^^^^^^^^^^^^
JSON
----
.. literalinclude:: ../examples/response/notification.json
:language: json
:linenos:

XML
---
.. literalinclude:: ../examples/response/notification.xml
:language: xml
:linenos:
webhook/*

0 comments on commit e93873e

Please sign in to comment.