šŸŒ Please help us test: API Column and Webhook action

Ask for Help
3

Updated: The Glide API

This is a quick reference on how to implement a Glide API endpoint. API endpoints are used for the API column and the webhook action.

Implementing your endpoint

The endpoint must be HTTPS and support the POST method. Glide will send a JSON request body. The format of the body differs between the API column and the Webhook action.

The API column

For the API column, the request body will contain the following fields:

  • hookKind is the string api-column.
  • appID is the calling appā€™s ID.
  • params is an object containing one field per argument passed to the API column. Its format is described further down.

Hereā€™s an example request body:

{
    "hookKind": "api-column",
    "appID": "wZWcgQbqV2pYGRas3qRH",
    "params": {
        "pokemon": {
            "type": "string",
            "value": "Bulbasaur"
        }
    }
}

The endpoint should produce a success status code with a JSON body of the same format as an argument (see below), like this:

{
    "type": "string",
    "value": "Known as the Seed PokƩmon, Bulbasaur can survive for days solely on sunlight."
}

If the endpoint produces an error status code, Glide will ignore the error and the value for the column in that row in Glide will be empty. This might change in the future, for example by throttling or disabling endpoints that return too many errors.

Caveats

  • Glide doesnā€™t currently cache the results of API column endpoint calls, and there is no throttling mechanism from Glideā€™s side, so be careful about not overloading your server. For example, if you add an API column to a sheet with a thousand rows and then scroll around in the Data Editor, your server will receive hundreds of API calls in very short order. You probably also donā€™t want to do rollups over an API column.
  • Thereā€™s no guarantee that the API column endpoint will be called at specific times. Right now Glide calls the endpoint right away whenever it needs the data from it, but we might introduce caching, throttling, or other measures.

Webhook action

  • hookKind is the string app-action.
  • appID is the calling appā€™s ID.
  • idempotencyKey is a unique string identifying the webhook request. Webhooks will be retried if they fail, but it is possible that webhooks will be called with the same invocation more than once in very rare circumstances. You may use the idempotencyKey to ensure you only service the request exactly once.
  • timestamp is the approximate date/time when the action was triggered.
  • params is an object containing one field per argument passed to the API column. Its format is described below.

Glide will try a webhook endpoint up to five times to improve delivery reliability. The response body is ignored, but HTTP status codes are respected. HTTP 2xx is treated as a success, HTTP 3xx is respected and followed, and all other statuses, including socket connection failures, are treated as failures and are eligible for retrying.

Retries occur on an exponential backoff schedule, but attempt timing is not precise. You may expect retries to follow this schedule with up to two additional minutes of delay:

Failed attempts Retry after
1 2 minutes
2 4 minutes
3 8 minutes
4 16 minutes
5 never

The params object

For both kinds of calls, Glide sends a params field, which is an object with one field per argument passed.

Each argument is an object with two fields:

  • type is the type of the argument. It can be either "string", "number", "boolean", or "date-time".
  • value is the value. If the type is "string", this will be a string. For "number" it will be a number. For "boolean" a boolean. For "date-time" it will be a string encoding the date-time in simplified extended ISO format (ISO 8601).

Note that arguments might be missing if they are empty.

Authentication

Glide will send a password in the Authorization header like this:

Authorization: Basic 56e7ccd3-655a-47fc-a905-5ad05a5f50cd

You can look up the expected password in the webhook configuration in Glide. Your endpoint should check whether the correct password is sent, to make sure that it was really called from Glide.

7 Likes