webhook

Developers › REST API › Forms & Integrations

REST API · 3 endpoints

Complete for this group. Each operation below lists its parameters, request body, responses and errors. Every model they use is documented under Models used on this page, so you do not need another page to build a request. Base URL https://dev-api.sheetgo.com; send Authorization: Bearer sg_…. Latest version: https://dev-api.sheetgo.com/rest/reference/webhook (Markdown).

Conventions for every endpoint. Lists take page (from 1) and per_page (1-100, default 50), and total counts pages, not items. Collection URLs end with /. POST …/run returns 200 when the run is queued; poll GET …/run. Google Sheets use provider: "drive"; column fields take letters ("E"). Error bodies and status codes: api.html#api-errors.

Python recipes. API client helper.

A webhook is a private URL that lets external systems push data into a workflow over HTTP. Your app sends a JSON payload and Sheetgo lands it in the workflow — optionally triggering a full run — with no Google APIs or OAuth to manage on your side.

Use this endpoint to POST data to a workflow's webhook source.

Operations

GET/rest/beta/automations/{automation_id}/webhookRetrieve an automation's webhook

Returns the webhook bound to this automation's webhook source — most importantly its url, which is the address an external system POSTs data to.

A webhook is minted automatically when an automation is created with a webhook source; there is no endpoint to create one separately, and no way to rotate it. Deleting the automation deletes the webhook with it. Automations without a webhook source return 404.

Parameters

Name	In	Type		Description
`automation_id`	path	string	required	Automation id

Responses

Status	Meaning	Body
200	The automation's webhook	`WebhookOut`
401	Authentication failed or token is invalid	—
404	Automation has no webhook	—
422	Validation Error	`HTTPValidationError`

Example request

curl -s -X GET "https://dev-api.sheetgo.com/rest/beta/automations/AUTOMATION_ID/webhook" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"

Latest version: https://dev-api.sheetgo.com/rest/reference/webhook#get-rest-beta-automations-automation-id-webhook

POST/rest/beta/webhook/{public_id}Push values to a webhook and trigger its bound automation

Sends rows into a workflow through an automation's webhook source, and starts a run.

Answers 202 Accepted as soon as the data is stored and the run is queued — the run itself happens asynchronously, so a 202 means accepted, not finished. Poll GET /rest/beta/automations/{automation_id}/run for the outcome.

Safe retries. Send an Idempotency-Key header (any unique string, 1-255 printable characters) and reuse it when you retry the same push. Sheetgo then runs the automation once and answers the retry with the first response plus Idempotent-Replayed: true, for 24 hours. A server error (5xx) is not remembered, so retrying it runs again.

Get the public_id from GET /rest/beta/automations/{automation_id}/webhook. Treat it as a secret.

Parameters

Name	In	Type		Description
`public_id`	path	string	required	The webhook's public identifier, from the automation's webhook endpoint.
`Idempotency-Key`	header	string	optional	Optional. Reuse the same value when retrying a push so it is processed only once.

Request body (required)

application/json · WebhookBody

Field	Type		Description
`async_dispatch`	boolean	optional	Default False — the automation is dispatched synchronously and the 202 is returned once dispatch has started. Pass True to dispatch asynchronously and return 202 as soon as the request is accepted; useful for high-throughput producers. Default: `false`
`run_workflow`	boolean	optional	If True, after this automation finishes, the parent workflow's other automations are re-run synchronously. Default: `false`
`values`	array of array of string	required	Tabular values to push (rows of strings) Min items: `1`

Responses

Status	Meaning	Body
202	Accepted; dispatch started	any
400	Malformed body, invalid `Idempotency-Key`, or webhook not bound to a webhook-source automation	—
401	Auth failed	—
404	Webhook not found or not owned by caller	—
409	A request with the same `Idempotency-Key` is still being processed (`idempotency_in_progress`)	—
413	Values exceed row/byte cap	—
422	Invalid request body (FastAPI validation error), or the `Idempotency-Key` was already used with a different body (`idempotency_key_reused`)	—

Example request

curl -s -X POST "https://dev-api.sheetgo.com/rest/beta/webhook/PUBLIC_ID" \
  -H "Authorization: Bearer $SHEETGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

Latest version: https://dev-api.sheetgo.com/rest/reference/webhook#post-rest-beta-webhook-public-id

GET/rest/beta/workflows/{workflow_id}/webhooksList a workflow's webhooks

Lists every webhook across the workflow's automations, so you can find the right url without knowing which automation owns it. Paginated with the standard page / per_page envelope. A workflow with no webhook sources returns an empty list, not a 404.

Parameters

Name	In	Type		Description
`workflow_id`	path	string	required	Workflow id
`page`	query	integer	optional	Page number, 1-based. Default: `1` · Min: `1`
`per_page`	query	integer	optional	Webhooks per page (1-100). Default: `50` · Min: `1` · Max: `100`

Responses

Status	Meaning	Body
200	Webhooks in the workflow	any
401	Authentication failed or token is invalid	—
422	Validation Error	`HTTPValidationError`

Example request

curl -s -X GET "https://dev-api.sheetgo.com/rest/beta/workflows/WORKFLOW_ID/webhooks" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"

Latest version: https://dev-api.sheetgo.com/rest/reference/webhook#get-rest-beta-workflows-workflow-id-webhooks

Models used on this page

Every request and response model referenced above, including nested ones (4). The full catalogue is on api-models.html.

`HTTPValidationError`

Field	Type		Description
`detail`	array of `ValidationError`	optional

`ValidationError`

Field	Type
`loc`	array of string or integer	required
`msg`	string	required
`type`	string	required

`WebhookBody`

Field	Type		Description
`async_dispatch`	boolean	optional	Default False — the automation is dispatched synchronously and the 202 is returned once dispatch has started. Pass True to dispatch asynchronously and return 202 as soon as the request is accepted; useful for high-throughput producers. Default: `false`
`run_workflow`	boolean	optional	If True, after this automation finishes, the parent workflow's other automations are re-run synchronously. Default: `false`
`values`	array of array of string	required	Tabular values to push (rows of strings) Min items: `1`

Used by: POST /rest/beta/webhook/{public_id}

`WebhookOut`

A webhook endpoint bound to one automation's webhook source.

Field	Type		Description
`active`	boolean	optional	False once the webhook has been deleted. A deleted webhook stops accepting pushes; webhooks are removed with their automation, never on their own. Default: `true`
`automation_id`	string	nullable	Id of the automation this webhook feeds. Null only for a webhook that is not yet bound to one.
`created_at`	string (date-time)	nullable	When the webhook was minted, ISO 8601.
`public_id`	string	required	The webhook's public identifier — the `{public_id}` path segment in `url`. Treat it as a secret: anyone holding it can push data to the automation.
`url`	string	required	Full URL to POST your JSON payload to. This is the value to configure in the external system that will push data.

Used by: GET /rest/beta/automations/{automation_id}/webhook