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.

[Jesse_St_Charle]

aryeh:

Saving Scheduled Dashboard PDFs to Dropbox (3.46+)

Is not accessible. I get “Sorry, you don’t have access to that topic!” when following that link.

[aryeh]

Hi Jesse,

Thanks for your note. I am one of the engineers working on Looker’s scheduling/data delivery functionality. Unfortunately, it is not currently possible to use Zapier to save PDFs to Dropbox (the technical reason is that they don’t support saving binary data). We are actively working on workarounds to solve this problem. If you are relatively technical, a good solution would be to write your own webhook service (for example, using Heroku or Amazon Lambda).

warm regards,
aryeh

[tig]

Making this post accessible again on July 6th.

[kay2]

It looks like there is a limit on the number of rows I can send in a webhook, when sending a JSON the attachment is empty when I try to send over 1k rows.

[Arkadi_Tereshen]

Hi, is there a way to find out what the Looker user was who initiated the call? We want to do some processing of data via webhook and then notify user back it’s available for download or something like this.

[lauren_boltz]

Hi @Arkadi_Tereshen,

We can utilize the scheduled_plan Explore in i__looker, Looker’s tool for creating Looker Usage and Metadata Reports to determine the Looker Users that created schedules by their User ID.

You can access this Explore by the following URL, replacing <my.looker.com> at the beginning of the URL with the address of your Looker instance. This Explore is pairing User ID with a Schedule type, so we may determine what users have created Schedules with Webhook Payloads, or other Schedule options:

https://my.looker.com/explore/system__activity/scheduled_plan?fields=scheduled_plan_destination.type...

I hope this information is helpful!

Cheers,

Lauren
Looker Support

[polmar]

Hello,

I’ve tried everything I could think of, but I have not been able to send a PDF using webhooks and Zapier, I’m always end up receiving a TXT. What I’m doing wrong? How can I decode the txt into a pdf?

Thanks in advance,

Pol