Webhooks
Webhooks are a simple way of allowing other services to send any changes directly to SheetDream, instead of making SheetDream poll for them via the API Tasks data source.
To enable and setup webhooks, it's as simple as creating a new spreadsheet (or table in Airtable) called "webhooks":
And here is what the spreadsheet looks like:
A description of the fields:
Field Name | Description |
target | The target table (spreadsheet) that this particular webhook should be importing data into. |
expression | A JSONata expression that will be applied to the incoming data. This expression will transform the incoming data to a simple JSON object that can be imported into the target spreadsheet. |
response | A JSONata expression that will be applied to the incoming data. This will transform into a response JSON object that the service calling the webhook expects to get returned from the webhook. See below for how this object should be formatted. |
The JSONata expression for the response field should evaluate to an object that looks like this:
{
"statusCode": 200, // can be any status code, just must be a number
"headers": {
... // any set of HTTP headers can be put here
},
"body": "" // can be string or JSON
}
After a synchronization occurs, you can retrieve the URL(s) for your new webhook(s) by issuing a GET request to the following endpoint with your admin user:
https://api.plutodream.com/sheetdream/api/<project_id>/webhooks
This endpoint will return a 401 Unauthorized for any non-admin level user. This is to prevent from others snooping on what webhooks you have available and trying to push random data to them.
From there, you can send data to a webhook by using a POST request. Note that webhooks do not require any authorization to call. Anyone or any service that has the URL can push data into your datasets. The webhook id below will be whatever the internal SheetDream _id value is:
https://api.plutodream.com/sheetdream/api/<project_id>/webhooks/<webhook_id>
When you POST to that endpoint, SheetDream will recognize you're interacting with the special webhooks table. It will take the incoming data in the POST body, and will run your JSONata expression against it. It will then attempt to import the result into your specified target spreadsheet.
The expression field should evaluate to something that looks like this:
{
"Column 1": ..,
"Column 2": ..,
..
}
In other words: a flat JSON object with no nesting. Simple key/value pairs only. If you do not adhere to this format, SheetDream will simply throw out the result and will not import anything into the target table.
The response field has no restrictions on what it needs to evaluate to. It should evaluate to some sort of JSON result that the calling service expects the webhook to return.
If you want to test your JSONata expression, head on over to https://try.jsonata.org. You'll find a window very similar to the JSONata editor modals in the API Tasks section. You can paste in some example webhook data your third party API will be POSTing to SheetDream, and then work out the JSONata to get a result object that can be successfully imported into your spreadsheet.
Last modified 1yr ago