See Stacksync in action with a solution architect. Book a demo ↗
StacksyncDocs
StacksyncCommunityBook a demoContact Support
HomeTwo-way syncAgentic WorkflowsGeniesEnterprise OSMCPEDIConnectorsSecurity and Other ResourcesChangelogDevelopersAPI Reference
SyncsWebhooks

Sync webhooks

Create a sync webhook

POST
/v1/workspaces/{workspace_id}/bases/{base_id}/webhooks

Add a webhook to a sync. When an event of the notification_type happens, Stacksync posts the event as JSON to the URL with Authorization: Bearer <api_key>. The URL is checked to be reachable before the webhook is stored. Send validate_only: true to run the checks without storing.

Authorization

Authorizationstringheaderrequired

Bearer <key>, where <key> is a workspace API key or a user API key. See Authentication.

Path Parameters

workspace_id*integer

The workspace the resources belong to

base_id*string

The sync (a sync is called a base in these paths)

Formatuuid

Query Parameters

region*string

Data region of the sync

Value in"besg""usnv"

Request Body

The webhook to add. The example's host hooks.example.com is a placeholder: replace it with your own HTTPS endpoint; it must resolve publicly. hooks.example.com is a placeholder: replace it with your own host, which the API checks before saving (the example as written is refused).

application/json
  1. body

A webhook of the sync: where one type of notification is posted. A sync holds at most one webhook per notification type and URL

url*string

The https URL Stacksync posts the notification to: a public internet host that answers an OPTIONS request within 2 seconds, with none of the characters space < > # % { } | \ ^ ~ [ ] `

Formaturi
notification_type*string

base_activity (the sync was switched, edited or failed), real_time_issue_notification (records failed to sync) or backfill (an initial full read finished)

Value in"base_activity""real_time_issue_notification""backfill"
api_key*string

Sent as Authorization: Bearer <api_key> with every notification, so your endpoint can check the caller

validate_only?boolean

Run every check of the write and answer without writing: a refused write answers the error it would answer

Defaultfalse

Response Body

The webhook created

application/json
  1. response

One webhook

msg*string

What was done

webhook*

A webhook of the sync

Create a sync webhook
curl -X POST 'https://api.stacksync.com/v1/workspaces/0/bases/497f6eca-6276-4993-bfeb-53cbbbba6f08/webhooks?region=besg' \  -H 'Content-Type: application/json' \  -d '{  "url": "https://hooks.example.com/stacksync",  "notification_type": "real_time_issue_notification",  "api_key": "whsec_7f3a9c2e4b1d"}'
{  "msg": "Successfully created webhook",  "webhook": {    "webhook_id": "6a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",    "url": "https://hooks.example.com/stacksync",    "notification_type": "real_time_issue_notification",    "api_key": "whsec_7f3a9c2e4b1d"  }}

GETGet a sync webhook

Read one webhook of a sync.

POSTUpdate a sync webhook

Replace the URL, notification type and API key of a webhook. The URL is checked to be reachable before the change is stored. Send `validate_only: true` to run the checks without storing.