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