# Project / Webhook Configuration

## Configure webhooks for a repository

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"ConfigureWebhookDto":{"type":"object","properties":{"platform":{"type":"string","description":"Platform type (defaults to github)","enum":["github","azure-devops"],"default":"github"},"repositoryIdentifier":{"type":"string","description":"Repository identifier. GitHub: owner/repo. Azure DevOps: org/project/repo"},"webhookUrl":{"type":"string","description":"Base URL for webhooks (e.g., https://sfp-server.com). Defaults to DOMAIN config. The platform-specific path is appended automatically."},"pat":{"type":"string","description":"Personal Access Token (required for Azure DevOps if no stored integration exists)"}},"required":["repositoryIdentifier"]}}},"paths":{"/sfp/api/project/configuration/webhook":{"post":{"operationId":"ProjectWebhookConfigController_configureWebhooks","summary":"Configure webhooks for a repository","description":"Automatically registers all required webhooks for a repository. Supports both GitHub and Azure DevOps.\n\n**GitHub** (platform: 'github'):\n- Repository identifier format: owner/repo (e.g., 'octocat/hello-world')\n- Creates a single webhook with events: pull_request, pull_request_review, pull_request_review_comment, issue_comment, issues, push\n- Uses GitHub App authentication (configured via integrations)\n\n**Azure DevOps** (platform: 'azure-devops'):\n- Repository identifier format: org/project/repo (e.g., 'myorg/myproject/myrepo')\n- 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\n- Requires PAT with \"Service Hooks: Read & Write\" scope, or a stored Azure DevOps integration\n\n**Push Events & Build-on-Merge**:\nPush events trigger the build-on-merge workflow when:\n- Push is to a configured default branch (set in project configuration)\n- Push is to a release branch matching 'release-*' or 'release/*' patterns\n\n**Idempotency**: This endpoint is idempotent - calling it multiple times with the same URL will not create duplicate webhooks.\n\n**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.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigureWebhookDto"}}}},"responses":{"201":{"description":"Webhooks configured successfully","content":{"application/json":{"schema":{"type":"array","items":{"properties":{"id":{"type":"string","description":"Provider-specific webhook/subscription ID"},"url":{"type":"string","description":"The webhook URL"},"events":{"type":"array","items":{"type":"string"},"description":"Events that trigger the webhook"},"active":{"type":"boolean","description":"Whether the webhook is active"},"provider":{"type":"string","enum":["github","azuredevops"]},"secret":{"type":"string","description":"Webhook secret (only if newly generated)"}}}}}}},"403":{"description":"Forbidden - Requires role: owner"},"422":{"description":"Platform rejected the webhook configuration (e.g., insufficient permissions on Azure DevOps). The message includes the platform error detail."}},"tags":["Project / Webhook Configuration"]}}}}
```

## List webhook filter rules for a project

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/project/configuration/webhook/filters/{repositoryIdentifier}":{"get":{"operationId":"ProjectWebhookConfigController_getWebhookFilters","summary":"List webhook filter rules for a project","description":"Returns the webhook filter exclusion rules configured for a project.\nWhen a webhook matches a filter rule (eventType + branchPattern), the matching flows are NOT triggered.","parameters":[{"name":"repositoryIdentifier","required":true,"in":"path","description":"Repository identifier (e.g., flxbl-io/sf-core)","schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook filter rules"},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"Project not found"}},"tags":["Project / Webhook Configuration"]}}}}
```

## Replace webhook filter rules for a project

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"SetWebhookFiltersDto":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Repository identifier (e.g., \"flxbl-io/sf-core\")"},"webhookFilters":{"description":"Webhook filter exclusion rules to set (replaces all existing rules)","type":"array","items":{"$ref":"#/components/schemas/WebhookFilterRuleDto"}}},"required":["repositoryIdentifier","webhookFilters"]},"WebhookFilterRuleDto":{"type":"object","properties":{"eventType":{"type":"string","description":"Webhook event category to filter","enum":["push","pull_request"]},"branchPattern":{"type":"string","description":"Wildcard pattern for branch name. For push: the pushed branch. For pull_request: the target (base) branch."},"flowIds":{"description":"Specific flow IDs to exclude. If omitted, ALL flows for this event+branch are excluded.","type":"array","items":{"type":"string"}}},"required":["eventType","branchPattern"]}}},"paths":{"/sfp/api/project/configuration/webhook/filters":{"put":{"operationId":"ProjectWebhookConfigController_setWebhookFilters","summary":"Replace webhook filter rules for a project","description":"Replaces all webhook filter exclusion rules for a project.\nWhen a webhook matches a filter rule (eventType + branchPattern), the matching flows are NOT triggered.\n\n**Branch patterns** support wildcards: `release/*`, `release-*`, `main`, `*`\n- For `push` events: matches the pushed branch\n- For `pull_request` events: matches the target (base) branch\n\n**Flow filtering**: If `flowIds` is specified, only those flows are excluded. If omitted, ALL flows for that event+branch are excluded.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetWebhookFiltersDto"}}}},"responses":{"200":{"description":"Webhook filter rules updated"},"403":{"description":"Forbidden - Requires role: owner, application"},"404":{"description":"Project not found"}},"tags":["Project / Webhook Configuration"]}}}}
```

## List configured webhooks for a repository

> 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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/project/configuration/webhook/{platform}/{repositoryIdentifier}":{"get":{"operationId":"ProjectWebhookConfigController_listConfiguredWebhooks","summary":"List configured webhooks for a repository","description":"Retrieves all webhooks configured for the specified repository from the platform (GitHub or Azure DevOps).\n\n**GitHub**: Returns webhooks from GitHub API\n**Azure DevOps**: Returns Service Hook subscriptions from Azure DevOps API","parameters":[{"name":"platform","required":true,"in":"path","description":"Platform type","schema":{"enum":["github","azure-devops"],"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"path","description":"Repository identifier","schema":{"type":"string"}},{"name":"pat","required":false,"in":"query","description":"PAT for Azure DevOps (if no stored integration)","schema":{"type":"string"}}],"responses":{"200":{"description":"List of webhooks for the repository"},"403":{"description":"Forbidden - Requires role: owner"}},"tags":["Project / Webhook Configuration"]}}}}
```

## Delete a specific webhook

> 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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/project/configuration/webhook/{platform}/{repositoryIdentifier}/{webhookId}":{"delete":{"operationId":"ProjectWebhookConfigController_deleteConfiguredWebhook","summary":"Delete a specific webhook","description":"Deletes a specific webhook from the platform (GitHub or Azure DevOps).\n\n**GitHub**: Deletes the webhook by ID\n**Azure DevOps**: Deletes the Service Hook subscription by ID","parameters":[{"name":"platform","required":true,"in":"path","description":"Platform type","schema":{"enum":["github","azure-devops"],"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"path","description":"Repository identifier","schema":{"type":"string"}},{"name":"webhookId","required":true,"in":"path","description":"Webhook/subscription ID to delete","schema":{"type":"string"}},{"name":"pat","required":false,"in":"query","description":"PAT for Azure DevOps (if no stored integration)","schema":{"type":"string"}}],"responses":{"204":{"description":"Webhook deleted successfully"},"403":{"description":"Forbidden - Requires role: owner"}},"tags":["Project / Webhook Configuration"]}}}}
```