Skip to main content

Subscription Create

Creating 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 integrated system(s).

To create your Subscriptions you will need to know the UUID of the caterer locations for which you want notifications to be sent across the integration. These can be retrieved by making a Caterer List query. For each location, you will need to create a Subscription for every event you want to receive notifications for. As the integration functionality expands, there may be additional subscription options as well!

We recommend exploring EventEntity and EventKey to determine which available values are going to be useful for meeting your needs. You can find examples of how these subscriptions might look below.

Once your subscriptions are set up, you should now receive Subscription Notifications at the webhookUrl that was specified during Subscriber Create.

If you need to change the webhookUrl, you can use the Subscriber Update mutation to change the webhookUrl and/or name of your Subscriber

Mutation

Mutation

mutation CreateSubscription($subscriptionParams: CreateSubscriptionFields!) {
  createSubscription(subscriptionParams: $subscriptionParams) {
    subscription {
      eventEntity
      eventKey
      parentEntity
      parentId
      subscriberId
    }
  }
}

Variables

If you need your subscriberId you can run the Subscriber List query

Variables - Order Accepted

{
  "subscriptionParams": {
    "eventEntity": "Order",
    "eventKey": "accepted",
    "parentEntity": "Caterer",
    "parentId": "ezcater-caterer-id",
    "subscriberId": "your-subscriber-id"
  }
}

Variables - Menu Updated

{
  "subscriptionParams": {
    "eventEntity": "Mennu",
    "eventKey": "updated",
    "parentEntity": "Caterer",
    "parentId": "ezcater-caterer-id",
    "subscriberId": "your-subscriber-id"
  }
}

Variables - MenuCreationRequest Succeeded

{
  "subscriptionParams": {
    "eventEntity": "MenuCreationRequest",
    "eventKey": "succeeded",
    "parentEntity": "Caterer",
    "parentId": "ezcater-caterer-id",
    "subscriberId": "your-subscriber-id"
  }
}

Arguments

Argument Name

Description

subscriptionParams: CreateSubscriptionFields!

The input object for making new subscribers.

Return Type

Returns a CreateSubscriptionPayload.

Successful Responses

When the createSubscription mutation succeeds you can expect the response payload to look like:

Response

{
  "data": {
    "createSubscription": {
      "subscription": {
        "eventEntity": "Order",
        "eventKey": "accepted",
        "parentEntity": "Caterer",
        "parentId": "ezcater-caterer-id",
        "subscriberId": "your-subscriber-id"
      }
    }
  }
}

Failure Responses

When createSubscription mutation fails you can expect the response payload to look like:

Response

{
  "errors": [
    {
      "message": "Subscription could not be created.",
      "path": [
        "createSubscription"
      ],
      "extensions": {
        "type": "summary",
        "serviceName": "external-events",
        "code": "DOWNSTREAM_SERVICE_ERROR",
        "exception": {
          "message": "Subscription could not be created.",
          "locations": [
            {
              "line": 1,
              "column": 96
            }
          ],
          "path": [
            "createSubscription"
          ]
        }
      }
    }
  ],
  "data": {
    "createSubscription": null
  }
}

Receiving Notifications

Once you have set up your integration, you will begin to receive Event Subscription Notifications for any Subscriptions you have set up. Notifications will be sent to the webhookUrl specified during Subscriber creation. The notifications will provide basic information about the event that occurred, but for detailed information, you can query the API.

Notification

{
  "id": "[uuid of the notification]",
  "parent_type": "Caterer",
  "parent_id": "[uuid of the caterer]",
  "entity_type": "[type of event]",
  "entity_id": "[uuid of the order]",
  "key": "[entity event key]",
  "created_at": "[time]",
  "occurred_at": "[time]",
  "updated_at": "[time]",
  "payload":null
}

Notification - Order Accepted

{
  "id": "ezcater-notification-id",
  "parent_type": "Caterer",
  "parent_id": "ezcater-caterer-id",
  "entity_type": "Order",
  "entity_id": "your-ezcater-order-id",
  "key": "accepted",
  "created_at":  "2025-04-15 23:48:23 UTC",
  "occurred_at":  "2025-04-15 23:48:23 UTC",
  "updated_at":  "2025-04-15 23:48:23 UTC",
  "payload":null
}

Notification - Menu Updated

{
  "id": "ezcater-notification-id",
  "parent_type": "Caterer",
  "parent_id": "ezcater-caterer-id",
  "entity_type": "Menu",
  "entity_id": "your-ezcater-menu-version-id",
  "key": "updated",
  "created_at":  "2025-04-15 23:48:23 UTC",
  "occurred_at":  "2025-04-15 23:48:23 UTC",
  "updated_at":  "2025-04-15 23:48:23 UTC",
  "payload":null
}

Notification - MenuCreationRequest Succeeded

{
  "id": "ezcater-notification-id",
  "parent_type": "Caterer",
  "parent_id": "ezcater-caterer-id",
  "entity_type": "MenuCreationRequest",
  "entity_id": "your-ezcater-menu-creation-request-id",
  "key": "succeeded",
  "created_at":  "2025-04-15 23:48:23 UTC",
  "occurred_at":  "2025-04-15 23:48:23 UTC",
  "updated_at":  "2025-04-15 23:48:23 UTC",
  "payload":null
}

Validating Notifications

It is recommended to validate that the webhook subscription notifications 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:

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 webhookSecret provided to you when you created your subscription

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

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.

Related Articles
Did this answer your question?