# webhook

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.

Base URL: `https://dev-api.sheetgo.com`. Start page: https://dev-api.sheetgo.com/rest/reference.md

This page documents every endpoint of the group. Request and response shapes link to model pages; fetch the model pages an endpoint links before building a body.

Guide: [Rate Limiting](https://dev-api.sheetgo.com/rest/guides/rate-limiting.md)

Every endpoint is rate limited; see the guide [Rate Limiting](https://dev-api.sheetgo.com/rest/guides/rate-limiting.md).

<a id="post-rest-beta-webhook-public-id"></a>
## 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.

Authentication, any one of: `default`; `Developer Access`; `sheetgo-api-key`.

**Parameters**

| Name | In | Type | Required | Description | Allowed values / default / constraints |
| --- | --- | --- | --- | --- | --- |
| `public_id` | path | string | yes | The webhook's public identifier, from the automation's webhook endpoint. |  |
| `Idempotency-Key` | header | string, nullable | no | Optional. Reuse the same value when retrying a push so it is processed only once. |  |

**Request body**

Content type `application/json`. Required.

Body: [WebhookBody](https://dev-api.sheetgo.com/rest/reference/models/WebhookBody.md)

**Responses**

- `202` Accepted; dispatch started
- `404` Webhook not found or not owned by caller
- `400` Malformed body, invalid `Idempotency-Key`, or webhook not bound to a webhook-source automation
- `401` Auth failed
- `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`)

Read next: [WebhookBody](https://dev-api.sheetgo.com/rest/reference/models/WebhookBody.md).

<a id="get-rest-beta-automations-automation-id-webhook"></a>
## GET /rest/beta/automations/{automation_id}/webhook

**Retrieve 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**.

Authentication, any one of: `default`; `Developer Access`; `sheetgo-api-key`.

**Parameters**

| Name | In | Type | Required | Description | Allowed values / default / constraints |
| --- | --- | --- | --- | --- | --- |
| `automation_id` | path | string | yes | Automation id |  |

**Responses**

- `200` The automation's webhook. Schema: [WebhookOut](https://dev-api.sheetgo.com/rest/reference/models/WebhookOut.md)
- `401` Authentication failed or token is invalid
- `404` Automation has no webhook
- `422` Validation Error. Schema: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md), [WebhookOut](https://dev-api.sheetgo.com/rest/reference/models/WebhookOut.md).

<a id="get-rest-beta-workflows-workflow-id-webhooks"></a>
## GET /rest/beta/workflows/{workflow_id}/webhooks

**List 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.

Authentication, any one of: `default`; `Developer Access`; `sheetgo-api-key`.

**Parameters**

| Name | In | Type | Required | Description | Allowed values / default / constraints |
| --- | --- | --- | --- | --- | --- |
| `workflow_id` | path | string | yes | Workflow id |  |
| `page` | query | integer | no | Page number, 1-based. | default: `1`; min: 1 |
| `per_page` | query | integer | no | Webhooks per page (1-100). | default: `50`; min: 1; max: 100 |

**Responses**

- `200` Webhooks in the workflow
- `401` Authentication failed or token is invalid
- `422` Validation Error. Schema: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md).

---

More: start page https://dev-api.sheetgo.com/rest/reference.md, everything in one file https://dev-api.sheetgo.com/rest/llms-full.txt, OpenAPI https://dev-api.sheetgo.com/rest/openapi.json.