How to: Automate workflows with webhooks

How do webhooks work?

1. When Events occur, 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 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.

Set up webhooks on Spark

Only tenant-admin s can 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 Webhooks tab.

3. Select Enable webhooks.

4. Select New webhook.

5. Enter the Name.

6. Enter the Endpoint URL.

7. Select which Event types will trigger webhook messages.

8. Add Request headers and Query string parameters that may be needed for the webhook call to be consumed.

9. Enter a Description if you have one.

10. Select Add to add this webhook to the list.

11. Select Save to save the new webhook.

JSON object of event properties

In response to a user action, Spark sends the following JSON request to the external endpoint. 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 How to: Automate workflows with webhooks.
AuditType	Classification of the entity. Typically, this is 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
}

External receiver endpoint

The external 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:

Authorization	Example
Query string	POST /your-api?api_key=abcdef12345
Request header	POST HTTP/1.1 x-api-key: abcdef12345

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