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:

KeyTypeOptionalDescription
typestringNoThe event type. Examples include PRODUCT_UPDATED, ORDER_PLACED, and FISCAL_DAY_END
targetUuidstringYesA UUID provided only if the type of event targets a particular resource. For PRODUCT_UPDATED this would be a productUuid.
createdAtstringNoAn ISO8601 timestamp value for the exact time the event was created.
dataobjectNoThe 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

KeyDescription
X-GoTab-Event-TypeThe event type as a header.
X-GoTab-Event-Target-UUIDThe event targetUuid as a header
X-GoTab-Application-IDThe 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-SignatureIf 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:

KeyTypeDescription
itemNamesstring[]A full list of item names from the order.
itemTagsstring[]A full list of items tags the order contains.
spotNamestringThe name of the spot in which the order was placed.
totalnumberThe order total, including taxes and fees.
zoneNamestringThe 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

KeyTypeDescription
causeObjectThe update that triggered this category update. If a product caused this updated then this will be {"type": "PRODUT_UPDATED"}