Grubhub Webhooks API

openapi: 3.2.0
info:
  title: Grubhub Webhooks API
  version: '1.0'
  description: 'Operations tagged Webhooks across 2 of this provider''s published API definitions: grubhub-connect-webhooks-openapi.yml, grubhub-reporting-webhooks-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api-third-party-gtm-pp.grubhub.com
  description: preprod
- url: https://api-third-party-gtm.grubhub.com
  description: prod
tags:
- name: Webhooks
paths: {}
webhooks:
  '[Egress] Delivery Refund Update Webhook':
    post:
      tags:
      - Webhooks
      summary: Delivery refund update
      requestBody:
        description: Information about a Delivery Refund Update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeliveryRefundUpdate'
              description: Delivery Refund Update
      responses: {}
    servers:
    - url: https://api-third-party-gtm-pp.grubhub.com
      description: preprod
    - url: https://api-third-party-gtm.grubhub.com
      description: prod
  '[Egress] Delivery Status Update Webhook':
    post:
      tags:
      - Webhooks
      summary: Delivery status update
      requestBody:
        description: Information about a Delivery Status Update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeliveryStatusUpdate'
              description: Delivery Status Update
      responses: {}
    servers:
    - url: https://api-third-party-gtm-pp.grubhub.com
      description: preprod
    - url: https://api-third-party-gtm.grubhub.com
      description: prod
  '[Egress] Report Status Update Webhook':
    post:
      tags:
      - Webhooks
      summary: Report status update
      requestBody:
        description: Information about a requested report
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantReportStatusWebhook'
              description: Report Status Update
      responses: {}
    servers:
    - url: https://api-third-party-gtm-pp.grubhub.com
      description: preprod
    - url: https://api-third-party-gtm.grubhub.com
      description: prod
components:
  schemas:
    Assigned:
      allOf:
      - $ref: '#/components/schemas/DeliveryEvent'
      description: An event indicating the delivery has been assigned.
      required:
      - timestamp
      - type
    ReturnInitiated:
      allOf:
      - $ref: '#/components/schemas/DeliveryEvent'
      description: An event indicating the delivery is in-transit back to the pickup location in order to return some portion of the delivery's contents.
      required:
      - timestamp
      - type
    ProofOfDelivery:
      allOf:
      - $ref: '#/components/schemas/DeliveryEvent'
      - type: object
        properties:
          dropoff_image_details:
            $ref: '#/components/schemas/DropoffImageDetails'
      description: An event containing proof of delivery information.
      required:
      - timestamp
      - type
    Courier:
      description: A courier.
      properties:
        name:
          type: string
          description: The display name of the courier assigned to a delivery.
          example: Nick
        delivery_method:
          type: string
          description: Means of transportation by which a courier may be delivering.
          enum:
          - CAR
          - BIKE
          - SCOOTER
          - WALK
          example: CAR
        location:
          $ref: '#/components/schemas/GeoLocation'
      required:
      - delivery_method
      - location
      - name
    PickupVerificationDetails:
      properties:
        result:
          type: string
          description: The result of the pickup verification.
          example: SUCCESS
        capture_method:
          type: string
          description: The method used to capture the pickup verification.
          enum:
          - MANUAL_ENTRY
          - QR_SCAN
          - PHOTO
          example: QR_SCAN
        failure_reason:
          type: string
          description: The reason for a failed pickup verification. Null when result is SUCCESS.
        attempts_count:
          type: integer
          format: int32
          description: The total number of verification attempts made.
        photo_url:
          type: string
          description: A URL to the pickup verification photo. Null for code-match events.
    DropoffImageDetails:
      properties:
        photo_url:
          type: string
          description: A URL to the dropoff photo taken by the driver upon completing the delivery.
          example: http://www.grubhub.com/example.png
        photo_capture_time:
          type: string
          format: date-time
          description: The timestamp at which the dropoff photo was captured. Formatted as an ISO-8601 timestamp.
          example: '2024-05-28T00:00:00Z'
        photo_capture_location:
          $ref: '#/components/schemas/GeoLocation'
        photo_expiration_time:
          type: string
          format: date-time
          description: The timestamp when the dropoff photo will expire.
          example: '2024-05-28T00:00:00Z'
      required:
      - photo_capture_location
      - photo_capture_time
      - photo_expiration_time
      - photo_url
    Created:
      allOf:
      - $ref: '#/components/schemas/DeliveryEvent'
      description: An event representing the creation of a delivery.
      required:
      - timestamp
      - type
    DeliveryRefundUpdate:
      type: object
      description: Reports the final decision regarding a submitted delivery refund request to clients via webhook.
      properties:
        delivery_id:
          type: string
          format: uuid
          description: The UUID associated with the delivery.
          example: 0ec346bd-635a-4a07-8f35-44962a8bcc5b
        accepted:
          type: boolean
          description: Whether the refund was accepted or not.
          example: true
        reason:
          type: string
          description: The reason for accepting or rejecting the refund.
          example: DriverNotCourteous
        description:
          type: string
          description: Additional descriptive notes about the refund decision.
          example: Grubhub accepts the full refund amount.
        amounts:
          $ref: '#/components/schemas/RefundAmount'
      required:
      - accepted
      - delivery_id
      - reason
    ClientData:
      description: Partner/client-supplied reference identifiers for this delivery.
      properties:
        external_id:
          type: string
          description: The partner's own identifier for this delivery.
        external_merchant_id:
          type: string
          description: The partner's identifier for the merchant associated with this delivery.
        external_source:
          type: string
          description: The source system that supplied the external identifiers.
        reference_number:
          type: string
          description: A partner-supplied reference number for this delivery.
    EstimatedEventTimes:
      description: The latest known estimates for the delivery pickup and dropoff times. Will be the actual times if the event has already occurred.
      properties:
        picked_up:
          type: string
          format: date-time
          description: The estimated pickup time, or the actual pickup time if the pickup has already occurred. Formatted as an ISO-8601 timestamp.
          example: '2024-05-28T00:00:00Z'
        dropped_off:
          type: string
          format: date-time
          description: The estimated drop-off time, or the actual drop-off time if the pickup has already occurred. Formatted as an ISO-8601 timestamp.
          example: '2024-05-28T00:00:00Z'
      required:
      - dropped_off
      - picked_up
    Unassigned:
      allOf:
      - $ref: '#/components/schemas/DeliveryEvent'
      description: An event indicating the delivery has been unassigned. An unassigned delivery may still be reassigned to another driver later.
      required:
      - timestamp
      - type
    InTransit:
      allOf:
      - $ref: '#/components/schemas/DeliveryEvent'
      description: An event indicating the assigned courier has departed the restaurant with the delivery.
      required:
      - timestamp
      - type
    Delivery:
      description: The information and historical events associated with a delivery.
      properties:
        delivery_id:
          type: string
          format: uuid
          description: A unique identifier of this delivery.
          example: 0ec346bd-635a-4a07-8f35-44962a8bcc5b
        events:
          type: array
          description: A history of notable events that have occurred for this delivery.
          items:
            $ref: '#/components/schemas/DeliveryEvent'
        estimated_event_times:
          $ref: '#/components/schemas/EstimatedEventTimes'
        client_data:
          $ref: '#/components/schemas/ClientData'
      required:
      - delivery_id
      - estimated_event_times
      - events
    CourierAtDropoff:
      allOf:
      - $ref: '#/components/schemas/DeliveryEvent'
      description: An event indicating the assigned courier has arrived at the delivery's dropoff location.
      required:
      - timestamp
      - type
    PickupVerification:
      allOf:
      - $ref: '#/components/schemas/DeliveryEvent'
      - type: object
        properties:
          pickup_verification_details:
            $ref: '#/components/schemas/PickupVerificationDetails'
      description: An event containing pickup verification information.
      required:
      - timestamp
      - type
    PickedUp:
      allOf:
      - $ref: '#/components/schemas/DeliveryEvent'
      description: An event indicating the delivery has been picked up by the assigned courier.
      required:
      - timestamp
      - type
    ReturnCompleted:
      allOf:
      - $ref: '#/components/schemas/DeliveryEvent'
      description: An event indicating that the necessary portion of the delivery's contents have been successfully returned to the pickup location.
      required:
      - timestamp
      - type
    Canceled:
      allOf:
      - $ref: '#/components/schemas/DeliveryEvent'
      - type: object
        properties:
          source:
            type: string
            description: Types of actors who may update a delivery.
            enum:
            - CLIENT
            - GRUBHUB
            example: CLIENT
          reason_code:
            type: string
            description: Codes for reasons why a delivery was canceled.
            enum:
            - MERCHANT_NOT_READY_FOR_PICKUP
            - MERCHANT_UNABLE_TO_FULFILL_ORDER
            - MERCHANT_CLOSED
            - MERCHANT_PICKUP_DELAYED
            - MERCHANT_ITEM_MISSING
            - CUSTOMER_CONTENTS_ISSUE
            - ORDER_PICKED_UP_BY_ANOTHER_DRIVER
            - DRIVER_UNABLE_TO_FINISH_DELIVERY
            - UNABLE_TO_ASSIGN_DRIVER
            - DELIVERY_CANCELLATION_OTHER_REASON
            example: CUSTOMER_CANCEL
          reason_comment:
            type: string
            description: Additional detail about the cancellation.
            example: Customer no longer wants delivery.
      description: An event indicating that the delivery was canceled.
      required:
      - timestamp
      - type
    Delivered:
      allOf:
      - $ref: '#/components/schemas/DeliveryEvent'
      - type: object
        properties:
          dropoff_image_details:
            allOf:
            - $ref: '#/components/schemas/DropoffImageDetails'
            deprecated: true
            description: Use `dropoff_image_details` in the `ProofOfDelivery` event instead.
      description: An event indicating the delivery has been successfully delivered.
      required:
      - timestamp
      - type
    DeliveryEvent:
      description: An event during the course of a single delivery's lifecycle.
      discriminator:
        propertyName: type
      oneOf:
      - $ref: '#/components/schemas/Created'
      - $ref: '#/components/schemas/Assigned'
      - $ref: '#/components/schemas/Unassigned'
      - $ref: '#/components/schemas/CourierAtPickup'
      - $ref: '#/components/schemas/PickupVerification'
      - $ref: '#/components/schemas/PickedUp'
      - $ref: '#/components/schemas/InTransit'
      - $ref: '#/components/schemas/CourierAtDropoff'
      - $ref: '#/components/schemas/Delivered'
      - $ref: '#/components/schemas/ProofOfDelivery'
      - $ref: '#/components/schemas/ReturnInitiated'
      - $ref: '#/components/schemas/ReturnCompleted'
      - $ref: '#/components/schemas/Canceled'
      properties:
        type:
          type: string
          description: The type of this event.
          enum:
          - CREATED
          - ASSIGNED
          - UNASSIGNED
          - COURIER_AT_PICKUP
          - PICKED_UP
          - IN_TRANSIT
          - COURIER_AT_DROPOFF
          - DELIVERED
          - PROOF_OF_DELIVERY
          - RETURN_INITIATED
          - RETURN_COMPLETED
          - CANCELED
          - PICKUP_VERIFICATION
          example: PICKED_UP
        timestamp:
          type: string
          format: date-time
          description: The time at which this event occurred. Formatted as an ISO-8601 timestamp.
          example: '2024-05-28T00:00:00Z'
      required:
      - timestamp
      - type
    GeoLocation:
      description: The last known location of the courier.
      properties:
        lat:
          type: number
          format: double
          description: The latitude of the location.
          example: 41.88320791307697
        lng:
          type: number
          format: double
          description: The longitude of the location.
          example: -87.63142796027925
      required:
      - lat
      - lng
    DeliveryStatusUpdate:
      type: object
      description: Provides information about the status of a delivery and the courier assigned to it, pushed to clients via webhook.
      properties:
        update_type:
          type: string
          description: The type of a DeliveryStatusUpdate.
          enum:
          - DELIVERY_STATUS_UPDATE
          - COURIER_LOCATION_UPDATE
          - ETA_UPDATE
        delivery:
          $ref: '#/components/schemas/Delivery'
        courier:
          $ref: '#/components/schemas/Courier'
        tracking_url:
          type: string
          description: The url for the delivery tracking UI.
      required:
      - delivery
      - update_type
    RefundAmount:
      description: The amount of the refund requested, broken down into various categories.
      properties:
        delivery_fee:
          type: integer
          format: int32
          description: The amount of the refund requested to be taken from the delivery fee, formatted as cents.
          example: 100
          minimum: 0
        tip:
          type: integer
          format: int32
          description: The amount of the refund requested to be taken from the tip, formatted as cents.
          example: 333
          minimum: 0
        contents_value:
          type: integer
          format: int32
          description: The amount of the refund requested to be taken from the contents value, formatted as cents.
          example: 542
          minimum: 0
        return_fee:
          type: integer
          format: int32
          description: The amount of the refund requested to be taken from the return fee, formatted as cents.
          example: 50
          minimum: 0
      required:
      - contents_value
      - delivery_fee
      - return_fee
      - tip
    CourierAtPickup:
      allOf:
      - $ref: '#/components/schemas/DeliveryEvent'
      description: An event indicating the assigned courier has arrived at the delivery's pickup location.
      required:
      - timestamp
      - type
    MerchantReportStatusWebhook:
      type: object
      description: Webhook for reporting status updates.
      properties:
        report_uuid:
          type: string
          format: uuid
          description: A unique identifier for the report.
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
        download_report_request_url:
          type: string
          description: URL to download the report. Make a GET request to this URL to get the s3 download link. This field is empty for NO_DATA or ERROR status.
          example: https://api-gtm.grubhub.com/merchant/reporting/v1/reports/f47ac10b-58cc-4372-a567-0e02b2c3d479
        report_status:
          type: string
          description: Status of the report. Possible values are COMPLETE, ERROR, or NO_DATA.
          example: COMPLETE
        message:
          type: string
          description: Message providing additional information about the report status. This field is empty for COMPLETE status.
      required:
      - download_report_request_url
      - message
      - report_status
      - report_uuid
      title: Merchant Report Status Webhook
x-refined-from:
- grubhub-connect-webhooks-openapi.yml
- grubhub-reporting-webhooks-openapi.yml