Webhooks

Endpoints for managing webhook subscriptions. Webhooks allow CheckFlow to send real-time event notifications to a URL of your choice when things happen in your team.

For a general overview of webhooks in CheckFlow, see the Webhooks documentation.

List Webhook Subscriptions

Returns webhook subscriptions, optionally filtered by source and event type.

GET /api/web-hook/subscriptions

Request Headers

Header	Required	Description
`X-API-KEY`	Yes	Your API key

Query Parameters

Parameter	Type	Required	Default	Description
`source`	`string`	No	`ALL`	Filters by the source of the webhook (e.g. `zapier`).
`eventType`	`string`	No	`ALL`	Filters by event type. Values: `ALL`, `new_checklist`, `task_completed`, `file_uploaded`, `data_set.record.created`, `data_set.record.updated`, `data_set.record.deleted`.

Example Request

GET https://app.checkflow.io/api/web-hook/subscriptions?eventType=task_completed
X-API-KEY: your-api-key-here

Response Codes

Code	Description
`200`	Returns matching webhook subscriptions.
`401`	API key is missing or invalid.
`404`	No subscriptions found matching the criteria.

Create Webhook Subscription

Creates a new webhook subscription. When the specified event occurs, CheckFlow will send a POST request containing the event data to the targetUrl.

POST /api/web-hook/subscribe

Request Headers

Header	Required	Description
`X-API-KEY`	Yes	Your API key

Query Parameters

Parameter	Type	Required	Description
`source`	`string`	Yes	A label identifying the source of this subscription (e.g. `zapier`, `custom`).
`eventType`	`string`	Yes	The event that triggers the webhook. Values: `new_checklist`, `task_completed`, `file_uploaded`, `data_set.record.created`, `data_set.record.updated`, `data_set.record.deleted`.
`targetUrl`	`string`	Yes	The URL that CheckFlow will POST the event data to.
`templateKey`	`string` (GUID)	Conditional	Required when `eventType` is `new_checklist`. Optional for `task_completed` (see scope table below).
`taskKey`	`string` (GUID)	Conditional	Optional for `task_completed` (see scope table below).
`taskContentKey`	`string` (GUID)	Conditional	Required when `eventType` is `file_uploaded`. The key of the File Upload control to watch.

Event Type Requirements

`eventType`	Required Key
`new_checklist`	`templateKey` — fires when a new checklist is created from this template
`task_completed`	See scope options below
`file_uploaded`	`taskContentKey` — fires when a file is uploaded to this File Upload control
`data_set.record.created`	(none) — team-wide; fires when a record is added to any Data Set
`data_set.record.updated`	(none) — team-wide; fires when a record's values change
`data_set.record.deleted`	(none) — team-wide; fires when a record is deleted

task_completed Scope Options

The task_completed event supports three levels of scope, giving you fine-grained control over which completions trigger the webhook.

Scope	Parameters	Fires when…
Task-specific	`taskKey`	That specific task is completed in any checklist
Template-scoped	`templateKey`	Any task is completed in any checklist created from that template
Team-wide	(neither key)	Any task is completed anywhere in your team

If you supply both taskKey and templateKey for a task_completed subscription, only taskKey is used.

Example Requests

Subscribe to new checklists:

POST https://app.checkflow.io/api/web-hook/subscribe?source=custom&eventType=new_checklist&targetUrl=https://example.com/hooks/new-checklist&templateKey=0e7ad584-7788-4ab1-95a6-ca0a5b444cbb
X-API-KEY: your-api-key-here

Subscribe to a specific task completion:

POST https://app.checkflow.io/api/web-hook/subscribe?source=custom&eventType=task_completed&targetUrl=https://example.com/hooks/task-done&taskKey=07072bc4-f1eb-4536-819a-1ddb7dc109a1
X-API-KEY: your-api-key-here

Subscribe to any task completion in a template:

POST https://app.checkflow.io/api/web-hook/subscribe?source=custom&eventType=task_completed&targetUrl=https://example.com/hooks/task-done&templateKey=0e7ad584-7788-4ab1-95a6-ca0a5b444cbb
X-API-KEY: your-api-key-here

Subscribe to any task completion in your team:

POST https://app.checkflow.io/api/web-hook/subscribe?source=custom&eventType=task_completed&targetUrl=https://example.com/hooks/task-done
X-API-KEY: your-api-key-here

Subscribe to file uploads:

POST https://app.checkflow.io/api/web-hook/subscribe?source=custom&eventType=file_uploaded&targetUrl=https://example.com/hooks/file&taskContentKey=50d58518-e049-4474-84c7-036236e52923
X-API-KEY: your-api-key-here

Subscribe to Data Set record changes:

POST https://app.checkflow.io/api/web-hook/subscribe?source=custom&eventType=data_set.record.updated&targetUrl=https://example.com/hooks/data-set
X-API-KEY: your-api-key-here

Data Set record events are team-wide — they fire for every Data Set in your team, so filter on dataSetId in your own handler if you only care about one. Bulk operations (bulk create, bulk delete and CSV replace) deliberately do not raise per-record events.

Example Response

{
  "id": "b90dd809-eefc-447e-8c17-5f0ca96df701",
  "source": "custom",
  "eventType": "task_completed",
  "targetURL": "https://example.com/hooks/task-done",
  "isActive": true,
  "taskKey": "07072bc4-f1eb-4536-819a-1ddb7dc109a1"
}

Response Codes

Code	Description
`200`	Returns the newly created subscription.
`400`	Missing or invalid `eventType`, or required key not provided.
`401`	API key is missing or invalid.

Delete Webhook Subscription

Deletes an existing webhook subscription.

DELETE /api/web-hook/unsubscribe

Request Headers

Header	Required	Description
`X-API-KEY`	Yes	Your API key

Query Parameters

Parameter	Type	Required	Description
`subscriptionId`	`string` (GUID)	Yes	The ID of the subscription to delete. Use List Webhook Subscriptions to find the ID.

Example Request

DELETE https://app.checkflow.io/api/web-hook/unsubscribe?subscriptionId=b90dd809-eefc-447e-8c17-5f0ca96df701
X-API-KEY: your-api-key-here

Response Codes

Code	Description
`200`	Subscription deleted successfully.
`400`	Could not parse `subscriptionId`.
`401`	API key is missing or invalid.

Payloads Delivered to Your Endpoint

When an event fires, CheckFlow sends an HTTP POST to the targetUrl on the subscription. These are the bodies it sends.

`data_set.record.created`

{
  "eventType": "data_set.record.created",
  "dataSetId": "9a3b6f88-1f2c-4a7d-9c62-1d7f5b0e4a11",
  "dataSetName": "Clients",
  "recordId": "c81f4a90-6f2b-4b8e-9a71-5d3c0e8b7a24",
  "values": {
    "4c2e0b1f-9a34-4c7e-b8d2-77f1a3e05c66": "Northwind Traders",
    "8b71d2c5-4e19-42a3-9f0b-6c1e8d4a2b93": "EMEA"
  }
}

`data_set.record.updated`

Contains only the fields that actually changed, with their previous and new values.

{
  "eventType": "data_set.record.updated",
  "dataSetId": "9a3b6f88-1f2c-4a7d-9c62-1d7f5b0e4a11",
  "dataSetName": "Clients",
  "recordId": "c81f4a90-6f2b-4b8e-9a71-5d3c0e8b7a24",
  "changes": {
    "8b71d2c5-4e19-42a3-9f0b-6c1e8d4a2b93": { "before": "EMEA", "after": "AMER" }
  }
}

`data_set.record.deleted`

{
  "eventType": "data_set.record.deleted",
  "dataSetId": "9a3b6f88-1f2c-4a7d-9c62-1d7f5b0e4a11",
  "dataSetName": "Clients",
  "recordId": "c81f4a90-6f2b-4b8e-9a71-5d3c0e8b7a24"
}

The keys inside values and changes are field ids, not field names. Use GET /api/data-sets/{dataSetId} to look up which field each id refers to. See Data Sets API.

warning

Bulk operations — bulk create, bulk delete and CSV replace — deliberately do not raise per-record events. A CSV import that replaces 500 records fires nothing at all, so a webhook is not a reliable way to mirror a Data Set that is maintained by import.

Finding the Keys a Subscription Needs

Key	How to find it
`templateKey`	`GET /api/template/templates` — see Templates.
`taskKey`	`GET /api/template/tasks` — see Templates.
`taskContentKey`	`GET /api/template/task-content` — see Templates.

Web Hooks — what webhooks are for, and when to use Zapier instead.
API Reference — generating the API key these endpoints need.
Data Sets API — resolving the field ids in a Data Set payload.
Zapier — subscribing to the same events without hosting an endpoint.

List Webhook Subscriptions​

Request Headers​

Query Parameters​

Example Request​

Response Codes​

Create Webhook Subscription​

Request Headers​

Query Parameters​

Event Type Requirements​

task_completed Scope Options​

Example Requests​

Example Response​

Response Codes​

Delete Webhook Subscription​

Request Headers​

Query Parameters​

Example Request​

Response Codes​

Payloads Delivered to Your Endpoint​

data_set.record.created​

data_set.record.updated​

data_set.record.deleted​

Finding the Keys a Subscription Needs​

Related Pages​

List Webhook Subscriptions

Request Headers

Query Parameters

Example Request

Response Codes

Create Webhook Subscription

Request Headers

Query Parameters

Event Type Requirements

task_completed Scope Options

Example Requests

Example Response

Response Codes

Delete Webhook Subscription

Request Headers

Query Parameters

Example Request

Response Codes

Payloads Delivered to Your Endpoint

`data_set.record.created`

`data_set.record.updated`

`data_set.record.deleted`

Finding the Keys a Subscription Needs

Related Pages