Project / Webhook Configuration

Configure webhooks for a repository

post

Automatically registers all required webhooks for a repository. Supports both GitHub and Azure DevOps.

GitHub (platform: 'github'):

Repository identifier format: owner/repo (e.g., 'octocat/hello-world')
Creates a single webhook with events: pull_request, pull_request_review, pull_request_review_comment, issue_comment, issues, push
Uses GitHub App authentication (configured via integrations)

Azure DevOps (platform: 'azure-devops'):

Repository identifier format: org/project/repo (e.g., 'myorg/myproject/myrepo')
Creates Service Hook subscriptions for: git.pullrequest.created, git.pullrequest.updated, git.pullrequest.merged, ms.vss-code.git-pullrequest-comment-event, workitem.commented, git.push
Requires PAT with "Service Hooks: Read & Write" scope, or a stored Azure DevOps integration

Push Events & Build-on-Merge: Push events trigger the build-on-merge workflow when:

Push is to a configured default branch (set in project configuration)
Push is to a release branch matching 'release-' or 'release/' patterns

Idempotency: This endpoint is idempotent - calling it multiple times with the same URL will not create duplicate webhooks.

Secret: A webhook secret is automatically generated if one doesn't exist. The secret is only returned in the response if it was newly generated.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

platformstring · enumOptional

Platform type (defaults to github)

Default: githubExample: githubPossible values:

repositoryIdentifierstringRequired

Repository identifier. GitHub: owner/repo. Azure DevOps: org/project/repo

Example: octocat/hello-world

webhookUrlstringOptional

Base URL for webhooks (e.g., https://sfp-server.com). Defaults to DOMAIN config. The platform-specific path is appended automatically.

Example: https://sfp-server.com

patstringOptional

Personal Access Token (required for Azure DevOps if no stored integration exists)

Example: pat_xxx...

Responses

201

Webhooks configured successfully

application/json

idstringOptional

Provider-specific webhook/subscription ID

urlstringOptional

The webhook URL

eventsstring[]Optional

Events that trigger the webhook

activebooleanOptional

Whether the webhook is active

providerstring · enumOptionalPossible values:

secretstringOptional

Webhook secret (only if newly generated)

403

Forbidden - Requires role: owner

422

Platform rejected the webhook configuration (e.g., insufficient permissions on Azure DevOps). The message includes the platform error detail.

post/sfp/api/project/configuration/webhook

POST /sfp/api/project/configuration/webhook HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 123

{
  "platform": "github",
  "repositoryIdentifier": "octocat/hello-world",
  "webhookUrl": "https://sfp-server.com",
  "pat": "pat_xxx..."
}

[]

List webhook filter rules for a project

get

Returns the webhook filter exclusion rules configured for a project. When a webhook matches a filter rule (eventType + branchPattern), the matching flows are NOT triggered.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

repositoryIdentifierstringRequired

Repository identifier (e.g., flxbl-io/sf-core)

Responses

200

Webhook filter rules

No content

403

Forbidden - Requires role: owner, member, application

404

Project not found

get/sfp/api/project/configuration/webhook/filters/{repositoryIdentifier}

GET /sfp/api/project/configuration/webhook/filters/{repositoryIdentifier} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Replace webhook filter rules for a project

put

Replaces all webhook filter exclusion rules for a project. When a webhook matches a filter rule (eventType + branchPattern), the matching flows are NOT triggered.

Branch patterns support wildcards: release/*, release-*, main, *

For push events: matches the pushed branch
For pull_request events: matches the target (base) branch

Flow filtering: If flowIds is specified, only those flows are excluded. If omitted, ALL flows for that event+branch are excluded.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

repositoryIdentifierstringRequired

Repository identifier (e.g., "flxbl-io/sf-core")

Example: flxbl-io/sf-core

Responses

200

Webhook filter rules updated

No content

403

Forbidden - Requires role: owner, application

404

Project not found

put/sfp/api/project/configuration/webhook/filters

PUT /sfp/api/project/configuration/webhook/filters HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 140

{
  "repositoryIdentifier": "flxbl-io/sf-core",
  "webhookFilters": [
    {
      "eventType": "push",
      "branchPattern": "release/*",
      "flowIds": [
        "build-on-merge"
      ]
    }
  ]
}

No content

List configured webhooks for a repository

get

Retrieves all webhooks configured for the specified repository from the platform (GitHub or Azure DevOps).

GitHub: Returns webhooks from GitHub API Azure DevOps: Returns Service Hook subscriptions from Azure DevOps API

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

platformstring · enumRequired

Platform type

Possible values:

repositoryIdentifierstringRequired

Repository identifier

Query parameters

patstringOptional

PAT for Azure DevOps (if no stored integration)

Responses

200

List of webhooks for the repository

No content

403

Forbidden - Requires role: owner

get/sfp/api/project/configuration/webhook/{platform}/{repositoryIdentifier}

GET /sfp/api/project/configuration/webhook/{platform}/{repositoryIdentifier} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Delete a specific webhook

delete

Deletes a specific webhook from the platform (GitHub or Azure DevOps).

GitHub: Deletes the webhook by ID Azure DevOps: Deletes the Service Hook subscription by ID

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

platformstring · enumRequired

Platform type

Possible values:

repositoryIdentifierstringRequired

Repository identifier

webhookIdstringRequired

Webhook/subscription ID to delete

Query parameters

patstringOptional

PAT for Azure DevOps (if no stored integration)

Responses

204

Webhook deleted successfully

No content

403

Forbidden - Requires role: owner

delete/sfp/api/project/configuration/webhook/{platform}/{repositoryIdentifier}/{webhookId}

DELETE /sfp/api/project/configuration/webhook/{platform}/{repositoryIdentifier}/{webhookId} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Last updated 2 hours ago

Was this helpful?