Public API
Setting Up Your Integration

18min
Creating a Subscriber
A Subscriber represents the integration itself. The Subscriber will manage where event notifications are sent to as well as what events you want to subscribe to. 
The webhookURL is the location you want the event notifications to be sent to.
Create Subscriber Mutation
To create the Subscriber, simply make a createSubscriber mutation request to the GraphQL endpoint.
Example Subscriber Mutation
GraphQL
mutation {
     createSubscriber(subscriberParams: {
          name: "Sample Integration",
               webhookUrl: "http://your-webhook-url.com/your-desired-endpoint"
          }) {
                     subscriber {
                          id
                          name
                          webhookUrl
                          webhookSecret
          }
     }
}
mutation {
     createSubscriber(subscriberParams: {
          name: "Sample Integration",
               webhookUrl: "http://your-webhook-url.com/your-desired-endpoint"
          }) {
                     subscriber {
                          id
                          name
                          webhookUrl
                          webhookSecret
          }
     }
}
﻿
Make sure you include the webhookSecret (line 10) in the values you want to return, and save it! The webhookSecret can only be seen on Subscriber creation, you will not be able to query for it afterwards.
The response will look something like this:
GraphQL
{
     "data": {
          "createSubscriber": {
          "subscriber": {
               "id": "0fc73833-fac0-4a4b-be38-b0a9baea4507",
               "name": "Sample Integration",
               "webhookUrl": "http://your-webhook-url.com/your-desired-endpoint",
               "webhookSecret": "A9e8018dac74463c632dea294494ca468f470c4df8513309d0e7ef8e265e08f7"
          }
     }
     }
}
{
     "data": {
          "createSubscriber": {
          "subscriber": {
               "id": "0fc73833-fac0-4a4b-be38-b0a9baea4507",
               "name": "Sample Integration",
               "webhookUrl": "http://your-webhook-url.com/your-desired-endpoint",
               "webhookSecret": "A9e8018dac74463c632dea294494ca468f470c4df8513309d0e7ef8e265e08f7"
          }
     }
     }
}
﻿
We currently only support creating one subscriber per API user. If you receive an error indicating that your subscriber could not be created, it may be that one has already been set up. Try running the subscribers query to see if any already exist.
You will also need the Subscriber ID in subsequent steps, so we recommend keeping track of it now.
﻿
Create Your Subscriptions
Subscriptions are how the subscriber determines what events it needs to send out notifications for. Once you’ve created your subscriber, you can customize the sorts of information that you may want to pull into your POS systems.
We currently only support Order Accepted, Order Cancelled and Menu Updated subscriptions.
Caterers Query
To create your subscriptions you will need to know the UUID of the locations for which you want notifications to be sent across the integration. These UUIDs can be retrieved by making a caterers query to the endpoint.
Example Caterers Query
GraphQL
query allCaterers {
     caterers { 
          uuid
          name
          storeNumber
          address {
               street
               street2
               city
               state
               zip
          }
     }
}
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 identify which UUID corresponds to which location.
﻿
Creating a Subscription Mutation
Now that you have your location UUID you can begin to create your subscriptions using the createSubscription mutation. For each location, you will need to send two mutations (one for accepted events and one for cancelled events). As the integration functionality expands, there may be additional subscription options as well!

As previously mentioned, the order accepted subscription triggers once an order has been accepted, not when the order is placed. It also triggers when an order has been updated and that update is accepted.

We recommend exploring the schema so that you can determine which available values are going to be useful for meeting your needs. You can find examples of how these subscriptions might look, in the next section.
If you need your subscriberId you can run the subscribers query:

query allSubscribers { 
     subscribers {
          id
     }
}
Example Subscription Mutations
Order Accepted
Order Cancelled
Menu Updated
mutation createsubscription {
     createSubscription (subscriptionParams: {
          subscriberId: "your-subscriber-id",
          eventKey: accepted, 
          eventEntity: Order,
          parentEntity: Caterer,
          parentId: "your-caterer-id"
     }) {
          subscription { 
          parentEntity 
          parentId 
          eventKey
          eventEntity
          }
     }
}
mutation createsubscription {
     createSubscription (subscriptionParams: {
          subscriberId: "your-subscriber-id",
          eventKey: accepted, 
          eventEntity: Order,
          parentEntity: Caterer,
          parentId: "your-caterer-id"
     }) {
          subscription { 
          parentEntity 
          parentId 
          eventKey
          eventEntity
          }
     }
}
﻿
Once your subscriptions are set up, you should now receive Event Notifications at the webhookUrl that was specified during Subscriber creation.
If you need to change the webhookUrl, you can use the updateSubscriber mutation to change the webhookUrl and/or name of your Subscriber.
﻿
Adding External IDs
ezCater’s API Support team will add your menu’s External IDs/PLUs to the ezCater menu for use in querying. The team will export your menu; you will fill in the PLUs for your menu items; and the team will import the information back into the ezCater menu. To initiate this process, contact [email protected]﻿
﻿
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.
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:
GraphQL
timestamp = x_ezcater_signature_header.split(“.”) [0]
     computed_signature_payload = [timestamp.to_i, request.body].join(".")
timestamp = x_ezcater_signature_header.split(“.”) [0]
     computed_signature_payload = [timestamp.to_i, request.body].join(".")
﻿
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 look something like:
GraphQL
signature = OpenSSL::HMAC.hexdigest("sha256", webhook_secret, computed_signature_payload)
signature = OpenSSL::HMAC.hexdigest("sha256", webhook_secret, computed_signature_payload)
﻿
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.
Updated 05 Dec 2024
Did this page help you?
Using GraphQL
Querying the Public API