Webhook Events and Payload

Webhooks allow applications to receive, via HTTP requests, information about when something happens in GoTab in realtime. Examples include receiving a webhook event when a product has been updated, a new order is submitted, or the fiscal day has ended at a location.

Webhook endpoints, headers, and events can be configured on the integrations dashboard.

📘
It's recommended to only subscribe to the events you actually need to in order to limit the number of requests that will be made to your endpoints

Webhook Payload Common Properties

All webhook urls will be POSTed to with a Content-Type header value of application/json and a JSON formatted payload object with the following properties:

Key	Type	Optional	Description
type	`string`	No	The event type. Examples include `PRODUCT_UPDATED`, `ORDER_PLACED`, and `FISCAL_DAY_END`
targetUuid	`string`	Yes	A UUID provided only if the type of event targets a particular resource. For `PRODUCT_UPDATED` this would be a `productUuid`.
createdAt	`string`	No	An ISO8601 timestamp value for the exact time the event was created.
data	`object`	No	The data for the event. The shape of the data varies based on the event being sent.

The payload's data and targetUuid properties will vary depending on the event type.

Delivery headers

In addition to any custom headers configured on the dashboard, the POST request will contain the following headers

Key	Description
X-GoTab-Event-Type	The event `type` as a header.
X-GoTab-Event-Target-UUID	The event `targetUuid` as a header
X-GoTab-Application-ID	The unique identifier of the application configured to receive the webhook event. This value will match the value shown on the integration dashboard page.
X-GoTab-Signature	If the webhook is configured with a `secret` then this value will be the SHA-256 hash of the response body encoded using the provided secret.

The UserAgent for the Webhook will also start with the value GoTab-WebhookAgent.

Example

> POST /webhook/endpoint HTTP/2

> Host: localhost:5000
> User-Agent: GoTab-WebhookAgent/1.0
> Content-Type: application/json
> X-GoTab-Event-Type: ORDER_PLACED
> X-GoTab-Event-Target_UUID: ord_xxxxxxxxx
> X-GoTab-Application-ID: int_xxxxxxx
> X-GoTab-Signature: [SHA256 HASH]

> {
>   "type": "ORDER_PLACED",
>   "targetUuid": "ord_xxxxxxxxx",
>   "createdAt": "2023-01-01T00:00:00.000Z",
>   "data": {/* ... */}
> }

Order Placed

This event is fired whenever an order has been placed at a location.

type: ORDER_PLACED
targetUuid: orderUuid

Data:

Key	Type	Description
itemNames	`string[]`	A full list of item names from the order.
itemTags	`string[]`	A full list of items tags the order contains.
spotName	`string`	The name of the spot in which the order was placed.
total	`number`	The order total, including taxes and fees.
zoneName	`string`	The name of the zone in which the order was placed.

Product Updated

This event is fired whenever a product at a location has been updated

type: PRODUCT_UPDATED
targetUuid: productUuid

Data

None

Category Updated

This event is fired whenever a category at a location is updated or a product in a category is updated. The cause property will have a field representing the chain of events leading to this event being fired.

type: CATEGORY_UPDATED
targetUuid: NULL (categories do not have a uuid property as of right now. Use the targetId in this case)
targetId: categoryId

Data

Key	Type	Description
cause	`Object`	The update that triggered this category update. If a product caused this updated then this will be `{"type": "PRODUT_UPDATED"}`