Using Webhook Notifications

When a diner places an order, we monitor that order and send several notifications to that diner based on the current status of that order. Those notifications go through our email and SMS channels and use Grubhub-branded messaging.

We understand that this may not work for all of our partners, so we offer a webhook channel as well. The webhook channel passes a payload of information about the order to a specified URI, which can then handle that payload and process it however you like.

To enable this notification channel, you'll have to set it at the cart level, overriding the diner preferences. POST to the /carts/{id}/notification_preferences as in the following example:

POST /carts/sjo9kZTMEeeynnPtDeD7JA/notification_preferences HTTP/1.1
Host: api-gtm.grubhub.com
Authorization: Bearer b7cb4642-d5cd-4aff-b180-8037d657cafd

{
    "channels": {
        "WEBHOOK": {
             "destinations": "http://someurl.com/path"
        }
    }
}

Here, we're attaching a WEBHOOK channel to the cart with ID sjo9kZTMEeeynnPtDeD7JA. Any time a notification event occurs with that cart, the Grubhub notification service will POST a WebhookPayload JSON object to the URI specified in WEBHOOK.destinations. While that value has a pluralized name, you can only specify one webhook to handle notifications.

Here's an example of what that webhook payload looks like:

{
    "webhook_sid": "testwebhooksecret",
    "order": {
        "id": "40d1b5db-7f89-47eb-8b06-fc36690a9fbc",
        "time_placed": "2017-09-15T17:48:38.666Z",
        "brand": "SEAMLESS",
        "diner_info": {
            "id": "o_PAIB6REeWhm3MRpi3OwA"
        },
        "fulfillment_info": {
            "fulfillment_type": "DELIVERY",
            "delivery_info": {
                "id": null,
                "address": {
                    "street_address1": "5303 Grover Ave",
                    "street_address2": null,
                    "address_locality": "Alamo",
                    "address_region": "NV",
                    "address_country": "US",
                    "postal_code": "89001",
                    "latitude": 37.643481,
                    "longitude": -115.754022,
                    "cross_streets": null
                },
                "is_green_indicated": false,
                "instruction": "fake",
                "contact_info": {
                    "phone": "(212)555-5553",
                    "email": "diner@email.com",
                    "name": "Diner Name"
                }
            },
            "pickup_info": null
        },
        "order_number": "874031888",
        "payments": {
            "payments": [
                {
                    "id": "id",
                    "payment_id": "payment id",
                    "payment_type": "Credit Card",
                    "amount": 296,
                    "cc_num_last_four": "7253",
                    "cc_type": "Visa"
                }
            ],
            "total": 296
        },
        "charges": {
            "diner_subtotal": 179,
            "fees": {
                "total": 100,
                "delivery": 100
            },
            "taxes": {
                "total": 17,
                "sales": 17,
                "delivery": 0
            },
            "tip": {
                "amount": 0,
                "type": "CASH"
            },
            "diner_grand_total": 296,
            "lines": {
                "lines": [
                    {
                        "name": "Italian Combo",
                        "special_instructions": "dinernotifications test",
                        "line_options": [],
                        "price": 429,
                        "quantity": 1,
                        "id": "288597705",
                        "menu_item_id": "13263833",
                        "diner_total": 429
                    },
                    {
                        "name": "Meatball Parm",
                        "special_instructions": "dinernotifications test 2",
                        "line_options": [],
                        "price": 1,
                        "quantity": 50,
                        "id": "3",
                        "menu_item_id": "3",
                        "diner_total": 50
                    }
                ]
            },
            "adjustments": [
              {
                "id": "UG87BVY8dg87gef4g478",
                 "association_id":"",
                 "association_type":"ORDER",
                 "amount": 123,
                 "notes": "for the extra avocado"
              }
            ]
          },
          "restaurant": {
            "id": "dea7e57c-edf5-4495-a87f-a40108af9bde6",
            "name": "Pippin's Boromir",
            "time_zone": "America/New_York",
            "address": {
                "street_address": "123 Sesame St",
                "locality": "Alphabet City",
                "region": "NY",
                "postal_code": "12345",
                "country": "USA",
                "latitude": "40.7",
                "longitude": "-73.9"
            },
            "phone": "212-345677"
        },
        "when_for": "2017-09-15T17:48:38.666Z",
        "fulfillment_estimate": {
            "time": "2017-09-15T17:48:38.666Z",
            "max_time": "2017-09-15T17:58:38.666Z"
        },
        "is_test": true
    },
    "status": "CONFIRMED"
}

We recommend that you build five different templates that your webhook uses based on the value of the status field. The possible statuses are "CONFIRMED", "READY_FOR_PICKUP", "OUT_FOR_DELIVERY", "ADJUSTED", and "CANCELLED".

Note: The webhook_sid field at the beginning is a security check to ensure that the payload comes from Grubhub. It will be the same for every payload you receive from us. When you get your API keys, we'll also give you this value. Because your webhook endpoint can be called by anyone, we need to use a shared secret to ensure you know where that request is coming from.

From this data, you should be able to build notifications that provide your diners satisfactory communications about the progress of their order.

Empowering Restaurants through Integration

Using Webhook Notifications