Webhooks: Connect Spark with external systems to automate workflows

How do webhooks work?

1. When an event occurs, Spark captures all the necessary event-related properties and packages them as JSON.

2. Next, Spark initiates an HTTP POST request to the URL configured for the webhook. It includes the JSON data from step 1 in the request body, along with the third-party server's API key preconfigured to be sent as a request header or query parameter.

3. The third-party server (receiving endpoint) then processes the request and initiates a callback to respond to the user's action.

Event types

Name	Description
SparkLogin	Spark login recorded.
CALogin	Coherent Assistant login recorded.
NotificationSparkReleaseDismissed	Notification for new Spark release dismissed.
AddProduct	Folder created.
UploadProduct	Folder uploaded.
EditProduct	Folder edited.
CloneProduct	Folder cloned.
DownloadProduct	Folder downloaded.
DeleteProduct	Folder deleted.
AddPermission	Permissions applied to folder.
RemovePermission	Permissions removed from folder.
ModifyPermission	Permissions modified for folder.
AddSection	Document section added.
DeleteSection	Document section deleted.
AddProductDocument	Document added.
DownloadProductDocument	Document downloaded.
EditProductDocument	Documented edited.
DeleteProductDocument	Document deleted.
PublishEngine	Service published.
CancelPublish	Service publishing was canceled.
UpdateEngine	Service updated.
EditEngine	Service was edited.
EditEngineVersion	Service version was edited.
ServiceActivated	Service activated.
ServiceDeactivated	Service deactivated.
CompareEngine	Service versions were compared.
RestoreEngine	Service version restored.
DownloadEngine	Service downloaded.
DeploymentRequest	Service version Deployment request made.
DeleteEngine	Service deleted.
DeleteEngineVersion	Service version deleted.
RecompileNeuron	Service version recompiled.
ShellSubmission	Operating a Shell submission made.
AddTransform	Transform added.
UpdateTransform	Transform updated.
DownloadTransform	Transform downloaded.
DeleteTransform	Transform deleted.
DownloadVersionOverview	Version overview downloaded.
DownloadAPICallHistory	API Call History downloaded.
DownloadEventViewer	Event viewer downloaded.
DownloadServiceLibrary	Service library downloaded.
UploadTestbed	Testbed uploaded.
GenerateTestCase	Test cases were generated.
AddTestCase	Test cases added to a testbed.
AddTestResult	Test result uploaded.
TestRunStarted	Testbed run started.
TestCasesExecuted	Test cases executed.
TestResultCompare	Test results compared.
TestResultAggregate	Test results aggregated.
APICallHistoryDataRetentionSuccess	API Call History data retention job succeeded.
APICallHistoryDataRetentionFailed	API Call History data retention job failed.
EventsDataRetentionSucccess	Event data retention job succeeded.
EventsDataRetentionFailed	Event data retention job failed.

Setting up webhooks on Spark

Please note that only tenant-admin users are able to set up webhooks on Spark.

1. To get started, click on your initials found on the top right corner of the Spark interface and select Options.

2. On the Tenant configuration page, navigate to the Webhook configuration tab.

3. Click on the Enable webhooks checkbox if it hasn't been already.

4. Click on the New webhook button to create a new webhook.

5. Complete the form with the following details:

   • A name to assign to this webhook.

   • Endpoint address.

   • Add the API key for your third-party server.

6. Click the Add button to save the new webhook.

7. Click the Save button on the Webhook configuration page.

Spark event handling: Spark's JSON packaging of essential event properties

In response to a user action, Spark generated the following JSON request to a third-party server. All the fields below are defined as string types.

Key	Value
FolderName	The folder associated with the event.
ServiceName	The service associated with the event.
EntityId	Id of the folder associated with the event.
UserAction	Event type, see Event types.
AuditType	The classification of the entity, typically this would be either Product for a folder or ProductEngine for a service.
Data.ProductName	Same as FolderName.
Data.EngineName	Same as ServiceName.
Data.FileName	Filename of the original service.
Data.ProductId	Same as EntityId.
Data.ServiceVersionId	version_id of the service.
Tenant	The tenant associated with the event.
RequestTimeStamp	Timestamp for the event.
RevisionId	null

Sample webhook body

{
    "FolderName": "Demo",
    "ServiceName": "PetRater",
    "EntityId": "9a42a837-92c6-452f-8991-89eb07b17f91",
    "UserAction": "UpdateEngine",
    "AuditType": "ProductEngine",
    "Data": {
      "ProductName": "Demo",
      "EngineName": "PetRater",
      "FileName": "PetRater",
      "ProductId": "9a42a837-92c6-452f-8991-89eb07b17f91",
      "ServiceVersionId": "7895a9ac-1dd3-47f0-8f56-60572116b61d"
    },
    "Tenant": "fieldengineering",
    "RequestTimeStamp": "2023-08-28T19:33:29.1709837Z",
    "RevisionId": null
}

Third-party server receiver endpoint

The third-party receiving endpoint should implement API key authorization. This token, provided by Spark, will be used by your endpoint for validation. The API Key can be included either in the query string, like POST /your-api?api_key=abcdef12345, or as a request header, such as POST HTTP/1.1 x-api-key: abcdef12345.

After successful authorization, your endpoint should extract JSON property values from the request body and initiate the callback process accordingly.

To filter events and respond correspondingly, please check the UserAction field for the event type. A comprehensive list of event types is provided below.