Google Click Fraud

Webhook


Webhooks can be used to instantly notify your server of changes to your Goodtill data. When enabled, an HTTP POST request will be sent to your webserver containing the type and ID of the data that has changed, you will then need to use the API to retrieve the relevant data. The webhook URL for your store can be configured in the backoffice by your store owner.

If you have any questions, please contact dev@thegoodtill.com

Setup

In order to configure webhooks for your store:

  • Login to the Goodtill backoffice with the store owner account.
  • Go to https://pos.thegoodtill.com/app/integrations/webhook
  • Enter the URL where you would like messages to be sent.
  • Choose which events you want to be notified about.
  • Click “Send test webhook” and verify that the message was received on your server.
  • Make a note of your “Verification Token” – see security section below.

Request Format

Example request:

{
    "message_id": "36bde03d-ce07-4008-901c-e7dce9c6bead",
    "datetime": "2018-11-01 10:20:00",
    "event": "sale.completed",
    "attempt": 1,
    "client": {
        "id": "3d07bb96-3f01-4265-ad1c-fba1f5ad1382",
        "name": "Goodtill Cafe",
        "subdomain": "goodtillcafe"
    },
    "outlet": {
        "id": "10709c98-6351-4259-8c78-06f01e2d42a6",
        "name": "Main Outlet"
    },
    "data": {
        "sale": {
            "id": "ed418d47-913c-4e5c-b440-7a314e0bf1b6",
            "url": "https://api.thegoodtill.com/api/sales/ed418d47-913c-4e5c-b440-7a314e0bf1b6"
        }
    }
}

Request fields:

FieldData
message_id Unique ID for the message. If message delivery fails, the same ID will be used for subsequent delivery attempts.
datetimeUTC datetime when the event occured.
eventType of event that has occurred (see list below).
attemptAttempt number for sending this message.
clientGoodtill store associated with the data.
outletStore outlet associated with the data. This may be null for data which is store-wide, such as in Customer data.
dataContains the type and ID of the data that has changed, including the URL where the data can be retrieved.

Security

In order to ensure that webhook requests are legitimately sent from Goodtill, you can perform the following validation before accepting a request:

  • Check that the “Goodtill-Verification-Token” header in the request is equal to the Verification Token shown in the backoffice when configuring the webhook URL.
  • Check that the request IP is 52.50.209.96

Retries

If a 200 response code is not received, the delivery of the message will be recorded as failed and the message will be sent again roughly an hour later.

A timeout will also be counted as a failure. The cutoff for receiving a response is 10 seconds.  If you are planning to perform a long-running task in response to a webhook message we strongly recommend returning a 200 response then performing the rest of the work in the background. This will prevent us sending the same message again even though it has already been accepted but no response was sent in time.

Events

Sales

Data format:

{
    ...
    "data": {
        "sale": {
            "id": "ed418d47-913c-4e5c-b440-7a314e0bf1b6",
            "url": "http://api.thegoodtill.com/api/sales/ed418d47-913c-4e5c-b440-7a314e0bf1b6"
        }
    }
}

The outlet field will be populated for these events.

There will be a delay between the sale state change on the POS and the webhook being sent as the POS app syncs data to our backend on a 30 second timer, so the delay will be between 0 and 30 seconds.

Events:

  • sale.completed – Sale moved to the completed state.
  • sale.transferred – Sale moved to the transferred state, .
  • sale.voided – Sale moved to the voided state.
Customers

Data format:

{
    ...
    "data": {
        "customer": {
            "id": "80bea0e2-b8f0-41ac-a861-afd8ad9fd416",
            "url": "https://api.thegoodtill.com/api/customer/details/80bea0e2-b8f0-41ac-a861-afd8ad9fd416"
        }
    }
}

The outlet field will not be populated for these events, as customers are store-wide.

Events:

  • customer.created – New customer record created.
  • customer.edited – Customer record updated.
Need Further Helps?

We are always happy to help with any issues you may be having. If you can't find what you're looking for within our support portal please send us a message by clicking the button below or call our support team on 0203 322 4095.