# Webhooks

## List all webhooks

> Retrieves all webhook configurations for the current account. Returns detailed information about each webhook including:\
>     \- Webhook ID and name\
>     \- URL endpoint\
>     \- Subscribed events\
>     \- Active/inactive status\
>     \- Creation and last update timestamps\
>     \- Delivery statistics (success/failure counts)\
>     \
>     Only webhooks belonging to the authenticated user's account are returned. Requires owner role to view webhook configurations.

```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":{"WebhookResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook"},"name":{"type":"string","description":"A human-readable name for the webhook"},"event":{"type":"string","description":"The event that triggers this webhook"},"provider":{"type":"string","description":"The webhook provider (e.g., github, slack)"},"config":{"description":"Provider-specific configuration","allOf":[{"$ref":"#/components/schemas/WebhookConfigResponseDto"}]},"timeout":{"type":"number","description":"Timeout in milliseconds"},"retryCount":{"type":"number","description":"Number of retry attempts"},"retryDelay":{"type":"number","description":"Delay between retries in milliseconds"},"status":{"type":"string","description":"Current status of the webhook","enum":["active","inactive","failed"]},"lastDeliveryAt":{"format":"date-time","type":"string","description":"Timestamp of the last delivery attempt","nullable":true},"errorCount":{"type":"number","description":"Number of consecutive delivery errors"},"createdBy":{"type":"string","description":"User who created the webhook"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"}},"required":["id","name","event","provider","config","timeout","retryCount","retryDelay","status","lastDeliveryAt","errorCount","createdBy","createdAt","updatedAt"]},"WebhookConfigResponseDto":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string","enum":["get","post","put","patch","delete"]},"headers":{"type":"object"},"filter":{"type":"object"}},"required":["url","method"]}}},"paths":{"/sfp/api/webhooks":{"get":{"operationId":"WebhookController_findAll","summary":"List all webhooks","description":"Retrieves all webhook configurations for the current account. Returns detailed information about each webhook including:\n    - Webhook ID and name\n    - URL endpoint\n    - Subscribed events\n    - Active/inactive status\n    - Creation and last update timestamps\n    - Delivery statistics (success/failure counts)\n    \n    Only webhooks belonging to the authenticated user's account are returned. Requires owner role to view webhook configurations.","parameters":[],"responses":{"200":{"description":"List of webhooks.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookResponseDto"}}}}},"401":{"description":"User is not authorized to list webhooks."},"403":{"description":"Forbidden - Requires role: owner"}},"tags":["Webhooks"]}}}}
```

## Create a new webhook

> Creates a new webhook configuration for receiving notifications about system events. Webhooks allow external systems to be notified when specific events occur within the SFP platform. \
>     \
>     The webhook configuration includes:\
>     \- URL endpoint to receive HTTP POST requests\
>     \- Events to subscribe to (e.g., deployment.started, deployment.completed)\
>     \- Optional headers for authentication\
>     \- Active/inactive status\
>     \- Retry configuration for failed deliveries\
>     \
>     Each webhook is associated with the creating account and can only be managed by users with owner role in that account.

```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":{"CreateWebhookDto":{"type":"object","properties":{"name":{"type":"string","description":"A human-readable name for the webhook"},"event":{"type":"string","description":"The event that triggers this webhook"},"provider":{"type":"string","description":"The webhook provider (e.g., github, slack)"},"config":{"description":"Provider-specific configuration","allOf":[{"$ref":"#/components/schemas/WebhookConfigDto"}]},"timeout":{"type":"number","description":"Timeout in milliseconds","default":10000},"retryCount":{"type":"number","description":"Number of retry attempts","default":3},"retryDelay":{"type":"number","description":"Delay between retries in milliseconds","default":60000}},"required":["name","event","provider","config"]},"WebhookConfigDto":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string","enum":["get","post","put","patch","delete"]},"headers":{"type":"object"},"filter":{"type":"object"}},"required":["url","method"]},"WebhookResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook"},"name":{"type":"string","description":"A human-readable name for the webhook"},"event":{"type":"string","description":"The event that triggers this webhook"},"provider":{"type":"string","description":"The webhook provider (e.g., github, slack)"},"config":{"description":"Provider-specific configuration","allOf":[{"$ref":"#/components/schemas/WebhookConfigResponseDto"}]},"timeout":{"type":"number","description":"Timeout in milliseconds"},"retryCount":{"type":"number","description":"Number of retry attempts"},"retryDelay":{"type":"number","description":"Delay between retries in milliseconds"},"status":{"type":"string","description":"Current status of the webhook","enum":["active","inactive","failed"]},"lastDeliveryAt":{"format":"date-time","type":"string","description":"Timestamp of the last delivery attempt","nullable":true},"errorCount":{"type":"number","description":"Number of consecutive delivery errors"},"createdBy":{"type":"string","description":"User who created the webhook"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"}},"required":["id","name","event","provider","config","timeout","retryCount","retryDelay","status","lastDeliveryAt","errorCount","createdBy","createdAt","updatedAt"]},"WebhookConfigResponseDto":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string","enum":["get","post","put","patch","delete"]},"headers":{"type":"object"},"filter":{"type":"object"}},"required":["url","method"]}}},"paths":{"/sfp/api/webhooks":{"post":{"operationId":"WebhookController_create","summary":"Create a new webhook","description":"Creates a new webhook configuration for receiving notifications about system events. Webhooks allow external systems to be notified when specific events occur within the SFP platform. \n    \n    The webhook configuration includes:\n    - URL endpoint to receive HTTP POST requests\n    - Events to subscribe to (e.g., deployment.started, deployment.completed)\n    - Optional headers for authentication\n    - Active/inactive status\n    - Retry configuration for failed deliveries\n    \n    Each webhook is associated with the creating account and can only be managed by users with owner role in that account.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookDto"}}}},"responses":{"201":{"description":"The webhook has been successfully created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResponseDto"}}}},"400":{"description":"Invalid webhook configuration."},"401":{"description":"User is not authorized to create webhooks."},"403":{"description":"Forbidden - Requires role: owner"}},"tags":["Webhooks"]}}}}
```

## Get a webhook by ID

> Retrieves detailed information about a specific webhook configuration. Returns comprehensive webhook details including:\
>     \- Complete configuration (URL, headers, events)\
>     \- Delivery statistics and recent delivery history\
>     \- Active/inactive status and last state change\
>     \- Retry configuration and backoff settings\
>     \
>     This endpoint is useful for debugging webhook delivery issues or verifying webhook configuration. Requires owner role.

```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":{"WebhookResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook"},"name":{"type":"string","description":"A human-readable name for the webhook"},"event":{"type":"string","description":"The event that triggers this webhook"},"provider":{"type":"string","description":"The webhook provider (e.g., github, slack)"},"config":{"description":"Provider-specific configuration","allOf":[{"$ref":"#/components/schemas/WebhookConfigResponseDto"}]},"timeout":{"type":"number","description":"Timeout in milliseconds"},"retryCount":{"type":"number","description":"Number of retry attempts"},"retryDelay":{"type":"number","description":"Delay between retries in milliseconds"},"status":{"type":"string","description":"Current status of the webhook","enum":["active","inactive","failed"]},"lastDeliveryAt":{"format":"date-time","type":"string","description":"Timestamp of the last delivery attempt","nullable":true},"errorCount":{"type":"number","description":"Number of consecutive delivery errors"},"createdBy":{"type":"string","description":"User who created the webhook"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"}},"required":["id","name","event","provider","config","timeout","retryCount","retryDelay","status","lastDeliveryAt","errorCount","createdBy","createdAt","updatedAt"]},"WebhookConfigResponseDto":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string","enum":["get","post","put","patch","delete"]},"headers":{"type":"object"},"filter":{"type":"object"}},"required":["url","method"]}}},"paths":{"/sfp/api/webhooks/{id}":{"get":{"operationId":"WebhookController_findOne","summary":"Get a webhook by ID","description":"Retrieves detailed information about a specific webhook configuration. Returns comprehensive webhook details including:\n    - Complete configuration (URL, headers, events)\n    - Delivery statistics and recent delivery history\n    - Active/inactive status and last state change\n    - Retry configuration and backoff settings\n    \n    This endpoint is useful for debugging webhook delivery issues or verifying webhook configuration. Requires owner role.","parameters":[{"name":"id","required":true,"in":"path","description":"Webhook ID","schema":{"type":"string"}}],"responses":{"200":{"description":"The webhook configuration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResponseDto"}}}},"401":{"description":"User is not authorized to view webhooks."},"403":{"description":"Forbidden - Requires role: owner"},"404":{"description":"Webhook not found."}},"tags":["Webhooks"]}}}}
```

## Delete a webhook

> Permanently deletes a webhook configuration. This action:\
>     \- Stops all future event deliveries to this webhook\
>     \- Cancels any pending retries for failed deliveries\
>     \- Removes the webhook configuration from the system\
>     \- Retains historical delivery logs for audit purposes\
>     \
>     This operation cannot be undone. The webhook must belong to the authenticated user's account. Requires owner role.

```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/webhooks/{id}":{"delete":{"operationId":"WebhookController_remove","summary":"Delete a webhook","description":"Permanently deletes a webhook configuration. This action:\n    - Stops all future event deliveries to this webhook\n    - Cancels any pending retries for failed deliveries\n    - Removes the webhook configuration from the system\n    - Retains historical delivery logs for audit purposes\n    \n    This operation cannot be undone. The webhook must belong to the authenticated user's account. Requires owner role.","parameters":[{"name":"id","required":true,"in":"path","description":"Webhook ID","schema":{"type":"string"}}],"responses":{"204":{"description":"The webhook has been successfully deleted."},"401":{"description":"User is not authorized to delete webhooks."},"403":{"description":"Forbidden - Requires role: owner"},"404":{"description":"Webhook not found."}},"tags":["Webhooks"]}}}}
```

## Update a webhook

> Updates an existing webhook configuration. All fields are optional - only provided fields will be updated. Common updates include:\
>     \- Changing the endpoint URL\
>     \- Adding/removing subscribed events\
>     \- Updating authentication headers\
>     \- Enabling/disabling the webhook\
>     \- Modifying retry configuration\
>     \
>     The webhook must belong to the authenticated user's account. Updates take effect immediately for new event deliveries. Requires owner role.

```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":{"UpdateWebhookDto":{"type":"object","properties":{"name":{"type":"string","description":"A human-readable name for the webhook"},"event":{"type":"string","description":"The event that triggers this webhook"},"config":{"description":"Provider-specific configuration","allOf":[{"$ref":"#/components/schemas/WebhookConfigDto"}]},"timeout":{"type":"number","description":"Timeout in milliseconds"},"retryCount":{"type":"number","description":"Number of retry attempts"},"retryDelay":{"type":"number","description":"Delay between retries in milliseconds"},"status":{"type":"string","description":"Current status of the webhook","enum":["active","inactive","failed"]}}},"WebhookConfigDto":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string","enum":["get","post","put","patch","delete"]},"headers":{"type":"object"},"filter":{"type":"object"}},"required":["url","method"]},"WebhookResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook"},"name":{"type":"string","description":"A human-readable name for the webhook"},"event":{"type":"string","description":"The event that triggers this webhook"},"provider":{"type":"string","description":"The webhook provider (e.g., github, slack)"},"config":{"description":"Provider-specific configuration","allOf":[{"$ref":"#/components/schemas/WebhookConfigResponseDto"}]},"timeout":{"type":"number","description":"Timeout in milliseconds"},"retryCount":{"type":"number","description":"Number of retry attempts"},"retryDelay":{"type":"number","description":"Delay between retries in milliseconds"},"status":{"type":"string","description":"Current status of the webhook","enum":["active","inactive","failed"]},"lastDeliveryAt":{"format":"date-time","type":"string","description":"Timestamp of the last delivery attempt","nullable":true},"errorCount":{"type":"number","description":"Number of consecutive delivery errors"},"createdBy":{"type":"string","description":"User who created the webhook"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"}},"required":["id","name","event","provider","config","timeout","retryCount","retryDelay","status","lastDeliveryAt","errorCount","createdBy","createdAt","updatedAt"]},"WebhookConfigResponseDto":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string","enum":["get","post","put","patch","delete"]},"headers":{"type":"object"},"filter":{"type":"object"}},"required":["url","method"]}}},"paths":{"/sfp/api/webhooks/{id}":{"patch":{"operationId":"WebhookController_update","summary":"Update a webhook","description":"Updates an existing webhook configuration. All fields are optional - only provided fields will be updated. Common updates include:\n    - Changing the endpoint URL\n    - Adding/removing subscribed events\n    - Updating authentication headers\n    - Enabling/disabling the webhook\n    - Modifying retry configuration\n    \n    The webhook must belong to the authenticated user's account. Updates take effect immediately for new event deliveries. Requires owner role.","parameters":[{"name":"id","required":true,"in":"path","description":"Webhook ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookDto"}}}},"responses":{"200":{"description":"The webhook has been successfully updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResponseDto"}}}},"400":{"description":"Invalid webhook configuration."},"401":{"description":"User is not authorized to update webhooks."},"403":{"description":"Forbidden - Requires role: owner"},"404":{"description":"Webhook not found."}},"tags":["Webhooks"]}}}}
```

## Queue a payload for delivery to a webhook

> Manually queues a custom payload for delivery to a specific webhook. This endpoint is useful for:\
>     \- Testing webhook connectivity and payload handling\
>     \- Replaying failed deliveries with corrected data\
>     \- Sending custom notifications outside normal event flow\
>     \
>     The payload is queued for asynchronous delivery and will follow the webhook's retry configuration if delivery fails. Returns a delivery ID for tracking. Requires owner or application role.

```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":{"DeliverWebhookDto":{"type":"object","properties":{"payload":{"type":"object","description":"The payload to deliver to the webhook endpoint"}},"required":["payload"]},"DeliveryResult":{"type":"object","properties":{"success":{"type":"boolean"},"statusCode":{"type":"number"},"error":{"type":"string"},"duration":{"type":"number"},"message":{"type":"string"},"providerDetails":{"$ref":"#/components/schemas/ProviderDetails"}},"required":["success","statusCode","duration"]},"ProviderDetails":{"type":"object","properties":{"method":{"type":"string","enum":["get","post","put","patch","delete"]},"url":{"type":"string"},"headers":{"type":"object"},"filtered":{"type":"boolean"},"queued":{"type":"boolean","description":"Whether the delivery is queued for processing"},"deliveryId":{"type":"string","description":"ID of the queued delivery"},"notFound":{"type":"boolean"},"eventName":{"type":"string"},"webhookId":{"type":"string"},"reason":{"type":"string"},"response":{"type":"object"}}}}},"paths":{"/sfp/api/webhooks/{id}/deliver":{"post":{"operationId":"WebhookController_deliverWebhook","summary":"Queue a payload for delivery to a webhook","description":"Manually queues a custom payload for delivery to a specific webhook. This endpoint is useful for:\n    - Testing webhook connectivity and payload handling\n    - Replaying failed deliveries with corrected data\n    - Sending custom notifications outside normal event flow\n    \n    The payload is queued for asynchronous delivery and will follow the webhook's retry configuration if delivery fails. Returns a delivery ID for tracking. Requires owner or application role.","parameters":[{"name":"id","required":true,"in":"path","description":"Webhook ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliverWebhookDto"}}}},"responses":{"202":{"description":"Webhook delivery has been queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryResult"}}}},"403":{"description":"Forbidden - Requires role: owner, application"}},"tags":["Webhooks"]}}}}
```

## Queue webhooks for an event

> Triggers webhook deliveries for all active webhooks subscribed to a specific event. This endpoint:\
>     \- Finds all active webhooks subscribed to the specified event\
>     \- Queues the payload for delivery to each matching webhook\
>     \- Processes deliveries asynchronously with configured retry policies\
>     \- Returns delivery IDs for tracking each webhook delivery\
>     \
>     This is the primary mechanism for event-driven webhook notifications in the system. Useful for manual event triggering or system integrations. Requires owner or application role.

```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":{"TriggerWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"The event that triggers the webhooks"},"payload":{"type":"object","description":"The event payload"}},"required":["event","payload"]},"DeliveryResult":{"type":"object","properties":{"success":{"type":"boolean"},"statusCode":{"type":"number"},"error":{"type":"string"},"duration":{"type":"number"},"message":{"type":"string"},"providerDetails":{"$ref":"#/components/schemas/ProviderDetails"}},"required":["success","statusCode","duration"]},"ProviderDetails":{"type":"object","properties":{"method":{"type":"string","enum":["get","post","put","patch","delete"]},"url":{"type":"string"},"headers":{"type":"object"},"filtered":{"type":"boolean"},"queued":{"type":"boolean","description":"Whether the delivery is queued for processing"},"deliveryId":{"type":"string","description":"ID of the queued delivery"},"notFound":{"type":"boolean"},"eventName":{"type":"string"},"webhookId":{"type":"string"},"reason":{"type":"string"},"response":{"type":"object"}}}}},"paths":{"/sfp/api/webhooks/trigger":{"post":{"operationId":"WebhookController_trigger","summary":"Queue webhooks for an event","description":"Triggers webhook deliveries for all active webhooks subscribed to a specific event. This endpoint:\n    - Finds all active webhooks subscribed to the specified event\n    - Queues the payload for delivery to each matching webhook\n    - Processes deliveries asynchronously with configured retry policies\n    - Returns delivery IDs for tracking each webhook delivery\n    \n    This is the primary mechanism for event-driven webhook notifications in the system. Useful for manual event triggering or system integrations. Requires owner or application role.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TriggerWebhookDto"}}}},"responses":{"202":{"description":"Webhook deliveries have been queued","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryResult"}}}}},"403":{"description":"Forbidden - Requires role: owner, application"}},"tags":["Webhooks"]}}}}
```