Integrating with the ezCater Public API

Optional Setup: Validating the Webhook

You have the option to validate whether the webhook you received actually came from ezCater.

The X-Ezcater-Signature header value consists of a timestamp and the signature, separated by a period. You can use the timestamp from this header, your webhookSecret value (from when you initially created the subscription), and the request body to verify this signature.

STEP 1: Create a computed signature payload from the webhook request data

You need two pieces of information for this step:

• The timestamp from the X-Ezcater-Signature header, which is the first portion before the period
• The request body

Concatenate these two values using a period to obtain a computed signature payload. For example, in Ruby this would look something like:

timestamp = x_ezcater_signature_header.split(“.”) [0]
computed_signature_payload = [timestamp.to_i, request.body].join(".")

STEP 2: Compute an HMAC signature of the request data

You need two pieces of information for this step:

• The computed signature payload from Step 1
• The webhook secret provided to you when you created your subscription

Compute an HMAC signature using your webhook secret and the computed signature payload. For example, in Ruby this would like something like:

signature = OpenSSL::HMAC.hexdigest("sha256", webhook_secret, computed_signature_payload)

STEP 3: Compare the provided signature with the computed one

You need two pieces of information for this step:

• The computed HMAC signature from Step 2
• The provided signature from the webhook request

Compare the computed HMAC signature with the value after the period in the X-Ezcater-Signature header. If these two values match, the request is valid. If they do not match, the request may have been tampered with or originated from an unauthorized source.

Querying the Public API

We recommend using a tool like GraphQL for viewing all the fields that can be queried from the Public API. This section will give a brief overview of our top-level queries.

Caterers Query

The Caterers query returns basic information about all of the catering locations that have been tied to the integration. This query is typically used to find Caterer UUIDs for creating Subscriptions and querying for a specific Menu.

Example query:

query allCaterers {
caterers {
uuid
name
storeNumber
address {
street
street2
city
state
zip
}
}
}

It may be useful to include the address information so that you can know which UUID corresponds to which location.

Order Query

When you receive an Event Notification, the payload will include the UUID of the Order that has changed.

You can use this UUID to query the Public API to see more details about the Order. Note that you must have permission within ezManage to access the store associated with an order UUID to be able to pull information about it.

Example query:

query orderById {
order(id: "UUID") {
orderNumber
orderSourceType
isTaxExempt event {
headcount timestamp
catererHandoffFoodTime
orderType
thirdPartyDeliveryPartner
}
caterer {
uuid
live
name
address {
street
city
state
}
}
totals {
customerTotalDue {
currency
subunits
}
salesTax {
currency
subunits
}
salesTaxRemittance {
currency
subunits
}
subTotal {
currency
subunits
}
tip {
currency
subunits
}
}
catererCart {
totals {
catererTotalDue
}
feesAndDiscounts (type: DELIVERY_FEE) {
__typename
name
cost {
currency
subunits
}
}
orderItems {
name
uuid
totalInSubunits {
subunits
currency
}
menuId
posItemId
menuItemSizeId
quantity
noteToCaterer
specialInstructions
customizations{
customizationId
posCustomizationId
name
quantity
customizationTypeName
}
}
}
}
}

Subscriber Query

The Subscriber query returns information about the Subscribers and Subscriptions for the integration. This query can be useful in determining if you have successfully created a Subscriber or Subscription. At this time we only allow one Subscriber per API user.

Example query:

query allSubscribers {
subscribers {
id
name
webhookUrl
subscriptions {
parentId
parentEntity
eventEntity
eventKey
}
}
}