Webhook Payload Description

[aryeh]

Webhooks are a powerful way to regularly deliver your data to your servers or third-party services like S3, Dropbox, or Google sheets through products like Zapier. Webhooks deliver data to a HTTPS URI with your data and some meta-information as JSON. Looker requires your server or service of choice to present a valid HTTPS certificate before sending data.

Here we document what the Webhook payload looks like. Before reading this document, you may want to confer with Scheduling Looks and Dashboards Using Webhooks (3.46+) for information about how to setup webhook delivery from Looker.

Formats

Looker supports various formats for representing the data in your Look or Dashboard. When scheduling a Look to send its data via Webhook, we support sending data in the following formats:

• CSV
• TXT
• JSON (“inline” and as a JSON string)
• HTML
• Excel

When scheduling a Dashboard to send its data via webhook, support sending data as a PDF. We will likely add more formats for both Looks and dashboards soon (note that EMail and Webhook formats slightly differ).

First Webhook Payload Example: CSV

Here are some example data for a CSV webhook payload —** CSV** is the format you probably want to reach for if you are looking for data in a text-based, structured, table format. The structure of the payload presented here will be identical for TXT, HTML, and JSON formats. XLSX, and PDF formats will also have the same structure, but must be treated specially because they are binary formats (more on this in the “Webhook Payload Example: PDF”). The Inline JSON format has a slightly different structure and is covered below.

{
    "attachment": {
        # Raw data
        "data": "Division,Revenue,Profit\nBrick + Mortar,3828101,739192\nOnline,7184918,4947684",
        "mimetype": "text/csv",
        "extension": "csv"
    },
    # Meta information
    "scheduled_plan": {
        # Name of the Look or Dashboard in Looker
        "title": "Sales — Year to Date",
        # Link to the Look or Dashboard in Looker
        "url": "https://look-your-data.looker.com/looks/19",
        "scheduled_plan_id": 37,
        "type": "look"
    }
}

The structure of the payload (i.e. the keys for the webhook data) for for JSON, TXT, and HTML are the same. In all these cases, data are encoded as a string under the attachment:data key of the webhook payload; for example for JSON:

"data": [{"Division": "Brick + Mortar", "Revenue": 3828101, "Profit": 739192}, {"Division": "Online", "Revenue": 7184918, "Profit": 4947684}]

Webhook Payload Example: Inline JSON

When specifying Inline JSON as your delivery format, the structure (i.e. the keys) of the payload will slightly differ. Whereas both the JSON and Inline JSON formats both encode data under the attachment:data key, Inline JSON specifies format specifies data as a JSON object and does not include the “mimetype” or “extension” keys.

Example data:

{
    "attachment": {
        # Note that data are JSON object and not a JSON string
        "data": [
            {
                Division: "Brick + Mortar",
                Revenue: 3828101,
                Profit: 739192
            },
            {
                Division: "Online",
                Revenue: 7184918,
                Profit: 4947684
            }
        ]
        # Note that mimetype and extension are not specified
    }
    "scheduled_plan": {
        "title": "Sales — Year to Date",
        "url": "https://look-your-data.looker.com/looks/37",
        "scheduled_plan_id": 11,
        "type": "look" 
    }
}

Webhook Payload Example: PDF

Whereas the CSV format is text-based, the PDF and XLSX are binary formats and are treated a little bit differently. The keys included in the webhook payload will be the same and data will still be contained in the attachment:data key. Yet data will be base64 encoded. Let’s look at an example:

{
    "attachment": {
        # Base64 encoded data
        "data": "TG9va2VyIHJvY2tzIQ==...",
        "mimetype": "application/pdf;base64",
        "extension": "pdf"
    },
    # Meta information
    "scheduled_plan": {
        # Name of the Look or Dashboard in Looker
        "title": "Sales Dashboard",
        "url": "https://look-your-data.looker.com/dashboard/42",
        "scheduled_plan_id": 23,
        "type": "dashboard"
    }
}

When saving a PDF document, you will need to decode the base64 data, save it, then open it in your application of choice (unfortunately Zapier does not currently allow saving binary files and thus PDFs cannot be saved, with Zapier, to services like Dropbox).

XLSX documents require the same procedure and we use the standard, but long mimetype application/vnd.openxmlformats-officedocument.spreadsheetml.sheet;base64.