Grist webhooks API
Document changes can trigger requests to URLs called webhooks.
OpenAPI Specification
openapi: 3.0.0
info:
description: 'An API for manipulating Grist sites, workspaces, and documents.
# Authentication
<SecurityDefinitions />
'
version: 1.0.1
title: Grist attachments webhooks API
servers:
- url: https://{gristhost}/api
variables:
subdomain:
description: The team name, or `docs` for personal areas
default: docs
security:
- ApiKey: []
tags:
- name: webhooks
description: Document changes can trigger requests to URLs called webhooks.
paths:
/docs/{docId}/webhooks:
get:
operationId: listWebhooks
tags:
- webhooks
summary: Webhooks associated with a document
description: 'Returns all webhooks configured for this document, including their
settings and delivery statistics.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
responses:
200:
description: A list of webhooks.
content:
application/json:
schema:
type: object
required:
- webhooks
properties:
webhooks:
$ref: '#/components/schemas/Webhooks'
post:
operationId: createWebhooks
tags:
- webhooks
summary: Create new webhooks for a document
description: 'Creates one or more webhooks that will POST to specified URLs when
data in the document changes. Returns the IDs of the created webhooks.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
requestBody:
description: an array of webhook settings
content:
application/json:
schema:
type: object
required:
- webhooks
properties:
webhooks:
type: array
items:
type: object
required:
- fields
properties:
fields:
$ref: '#/components/schemas/WebhookPartialFields'
responses:
200:
description: Success
content:
application/json:
schema:
type: object
required:
- webhooks
properties:
webhooks:
type: array
items:
$ref: '#/components/schemas/WebhookId'
/docs/{docId}/webhooks/{webhookId}:
patch:
operationId: modifyWebhook
tags:
- webhooks
summary: Modify a webhook
description: 'Update the configuration of an existing webhook, such as its URL,
enabled state, or event types.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- in: path
name: webhookId
schema:
type: string
required: true
requestBody:
description: the changes to make
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookPartialFields'
responses:
200:
description: Webhook updated successfully. Returns empty body.
delete:
operationId: deleteWebhook
tags:
- webhooks
summary: Remove a webhook
description: 'Permanently delete a webhook. Any pending deliveries in the queue
for this webhook will also be removed.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- in: path
name: webhookId
schema:
type: string
required: true
responses:
200:
description: Webhook deleted successfully.
content:
application/json:
schema:
type: object
required:
- success
properties:
success:
type: boolean
example: true
/docs/{docId}/webhooks/queue:
delete:
operationId: clearWebhookQueue
tags:
- webhooks
summary: Empty a document's queue of undelivered payloads
description: 'Clear all pending webhook deliveries for this document. Use this
if the queue has built up due to unreachable endpoints.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
responses:
200:
description: Queue cleared successfully. Returns empty body.
/docs/{docId}/webhooks/queue/{webhookId}:
delete:
operationId: clearWebhookQueueForWebhook
tags:
- webhooks
summary: Clear queue for a specific webhook
description: 'Clear the queue of pending payloads for a specific webhook.
Only document owners can call this endpoint.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- name: webhookId
in: path
required: true
schema:
type: string
description: ID of the webhook
responses:
200:
description: Queue cleared
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
components:
parameters:
docIdPathParam:
in: path
name: docId
schema:
type: string
description: A string id (UUID)
required: true
schemas:
WebhookId:
type: object
required:
- id
properties:
id:
type: string
description: Webhook identifier
example: xxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx
Webhook:
type: object
properties:
id:
type: string
format: uuid
example: xxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx
fields:
$ref: '#/components/schemas/WebhookFields'
usage:
$ref: '#/components/schemas/WebhookUsage'
WebhookBatchStatus:
type: object
nullable: true
required:
- size
- attempts
- status
properties:
size:
type: number
example: 1
attempts:
type: number
example: 1
errorMessage:
type: string
nullable: true
example: null
httpStatus:
type: number
example: 200
status:
type: string
example: success
WebhookRequiredFields:
type: object
required:
- name
- memo
- url
- enabled
- unsubscribeKey
- eventTypes
- isReadyColumn
- tableId
properties:
unsubscribeKey:
type: string
Webhooks:
type: array
items:
$ref: '#/components/schemas/Webhook'
WebhookFields:
allOf:
- $ref: '#/components/schemas/WebhookPartialFields'
- $ref: '#/components/schemas/WebhookRequiredFields'
WebhookPartialFields:
type: object
properties:
name:
type: string
example: new-project-email
nullable: true
memo:
type: string
example: Send an email when a project is added
nullable: true
url:
type: string
format: uri
example: https://example.com/webhook/123
enabled:
type: boolean
eventTypes:
type: array
items:
type: string
example:
- add
- update
isReadyColumn:
type: string
nullable: true
example: null
tableId:
type: string
example: Projects
WebhookUsage:
type: object
nullable: true
required:
- numWaiting
- status
properties:
numWaiting:
type: integer
status:
type: string
example: idle
updatedTime:
type: number
nullable: true
format: UNIX epoch in milliseconds
example: 1685637500424
lastSuccessTime:
type: number
nullable: true
format: UNIX epoch in milliseconds
example: 1685637500424
lastFailureTime:
type: number
nullable: true
format: UNIX epoch in milliseconds
example: 1685637500424
lastErrorMessage:
type: string
nullable: true
example: null
lastHttpStatus:
type: number
nullable: true
example: 200
lastEventBatch:
$ref: '#/components/schemas/WebhookBatchStatus'
securitySchemes:
ApiKey:
type: http
scheme: bearer
bearerFormat: 'Authorization: Bearer XXXXXXXXXXX'
description: Access to the Grist API is controlled by an Authorization header, which should contain the word 'Bearer', followed by a space, followed by your API key.