Direct Writes
If you only need to change a connection or a webhook, and it is not under an approval rule, keep using the direct endpoints:PUT /sdk-connections/{id}for settings.POST /sdk-connections/{id}/webhooks,PUT /sdk-webhooks/{id}, andDELETE /sdk-webhooks/{id}for webhooks.
bypassApproval: true to make the write anyway. This requires Bypass draft approvals access for SDK Connections, or the organization’s REST API always bypasses approval requirements setting.
Drafts and Publishing
A draft holds proposed changes against a snapshot of the connection and its webhooks from when the draft was opened. Nothing reaches your SDKs until the draft is published. Open a new draft:version, which you pass to the edit calls:
headers is a JSON-encoded object. A header or endpoint can reference a webhook secret as {{ SECRET_KEY }}. Responses to write calls leave webhook headers out. The read endpoints return them to callers who can edit the webhook.
Archive or restore the connection with PUT .../archive and {"archived": true} or {"archived": false}.
Publish to apply the draft to the live connection and its webhooks:
merged.
Auto-creating a draft on edit
Every edit endpoint (PUT .../settings, PUT .../archive, and the webhook endpoints) accepts the literal new in place of a version number. This opens a draft, applies the edit, and returns the revision in one call. Pass revisionTitle and revisionComment to label the new draft:
revisionTitle and revisionComment are ignored when editing an existing draft. An edit to new that changes nothing is refused, so it never opens an empty draft.
Revisions
An SDK Connection has one live revision and any number of open drafts. Statuses are the same as for Saved Group revisions:draft, pending-review, changes-requested, approved, merged, and discarded.
Reverting
POST .../{version}/revert restores the settings and webhooks that a published revision left the connection with. It creates a draft by default. Pass {"strategy": "publish"} to apply it at once. When the connection requires approval, that needs Bypass draft approvals access, unless the organization lets reverts bypass approval.
- Whether the connection is archived is not restored.
- A webhook that the revert brings back is created again with a new signing key, so update whatever verifies its signature. When the revert is applied at once, the response lists those webhooks in
recreatedWebhookIds.
Discarding and Reopening
POST .../discard abandons an open draft. POST .../reopen brings a discarded one back as a draft.
Scheduling a Publish
POST .../schedule-publish with {"scheduledPublishAt": "2027-01-31T09:00:00Z"} publishes the draft at that time. Send null to cancel. A draft that still needs approval must request review first.
A warning that would apply at publish is raised when you schedule, and ignoreWarnings acknowledges it. The scheduled publish goes ahead with what was acknowledged. If something new appears before it fires, such as a secret a webhook references being deleted, the publish stops, the draft stays open, and sdkConnection.revision.publishFailed is emitted.
Merge Conflicts
A draft falls behind when the live connection changes after the draft was opened. Changes to different settings, and to different webhooks, merge on their own. A conflict is two different changes to the same setting or the same webhook.sdkConnection (settings) and sdkWebhooks. For each, overwrite keeps the draft’s value and discard keeps the live value.
Approval Flows
When SDK Connection approvals are required, a draft must be approved before it can be published.POST .../recall-review withdraws a review request, and POST .../undo-review retracts your own verdict.
A draft that moves the connection to another Project or environment is reviewed under the rules of both where it leaves and where it lands.
Approval is not required when the caller has Bypass draft approvals access for SDK Connections in every Project involved, or when the organization enables REST API always bypasses approval requirements.
Blocked Publishes
A publish that can’t go ahead returns one422 listing every gate that blocks it. Each gate names the request flag that clears it, the permission that flag needs, or the route that resolves it:
A webhook that references a secret that doesn’t exist, or one not allowed for its endpoint, would fail every send. Saving such a webhook directly, or publishing a draft that adds or changes one, raises a warning. Staging it in a draft does not.
Both flags are accepted on every endpoint that runs a Custom Hook: the direct writes, the draft edits, rebase, publish, and revert. A successful publish reports what it bypassed in
bypassedGates.
Publishing With Other Changes
To publish an SDK Connection draft together with Feature Flag, Saved Group, Config, or Constant drafts as one all-or-nothing operation, usePOST /releases/publish-revisions.
Deleting
DELETE /sdk-connections/{id} deletes an archived connection. Deleting a live one is refused unless the organization enables REST API always bypasses approval requirements. Archive it first, directly or in a draft.
Permissions
- SDK Connections Full Access covers the whole lifecycle: creating a connection, opening and changing drafts, reviewing, publishing, reverting, archiving, and deleting. It is checked in the connection’s environment.
- Any change to a connection’s webhooks, in a draft or directly, also needs the SDK Webhooks permission, which that policy includes. A custom role with only the SDK Webhooks permission can still change webhooks directly, and each change is recorded as a revision.
- Bypass draft approvals for SDK Connections skips required review, allows an out-of-date draft to be force-published, and is what
skipHooksrequires. It is checked per Project.

