> For the complete documentation index, see [llms.txt](https://docs.coherent.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coherent.global/integrations/how-to-automate-workflows-with-webhooks.md).

# How to: Automate workflows with webhooks

## How do webhooks work?

```mermaid
flowchart LR
  A["User action<br>initiates event"] --> B["Webhook<br>JSON event data"] --> C["Third-party server<br>processes request"]
```

1. When [Events](/tenant-administration/events.md) 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](/navigation/options.md).
2. On the [Tenant configuration](/tenant-administration/tenant-configuration.md) 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 [#event-types](#event-types "mention").                                                          |
| `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

<details>

<summary></summary>

```json
{
    "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
}
```

</details>

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