Skip to content

Commit

Permalink
Merge pull request #34 from epilot-dev/docs/webhook
Browse files Browse the repository at this point in the history 
docs: add and cleanup webhook features
  • Loading branch information
@boringContributor
boringContributor authored Dec 6, 2023
2 parents 6ffbc63 + a7d5ade commit d017f7d
Show file tree
Hide file tree
Showing 3 changed files with 31 additions and 159 deletions.
190 changes: 31 additions & 159 deletions docs/webhooks.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar_position: 14
# Webhooks

[[API Docs](/api/webhooks)]
[[SDK](https://www.npmjs.com/package/@epilot/entity-client)]
[[SDK](https://www.npmjs.com/package/@epilot/webhooks-client)]

The epilot [Webhooks API](/api/webhooks) provides the possibility to subscribe to epilot public events. This will allow you to receive notifications with payload to your configured webhook URL every time events happen in your account.

Expand All @@ -15,174 +15,46 @@ Webhooks can be comfortably configured and managed by admin users in epilot port

[Webhooks API Documentation](/api/webhooks)

## Available events
For an overview about all events you can subscribe to with Webhooks you can call following endpoint `/v1/webhooks/configured-events`. The response will contain a list of event names and their labels in form:
* **eventName**: Name for identifying the event.
* **eventLabel**: Either a user friendly label, or the eventName itself.
When using the UI, you have the list of the available events in the drop down menu in webhook management form.

# Customization

In [Events Schemas](/api/webhooks) section you find the schemas of available events ready to register:
* [**Customer Request Created**](/api/webhooks#tag/events_schema): generated on incoming requests from JB Journeys
* [**Product Updated**](/api/webhooks#tag/events_schema_product_updated): generated when changing product information
* [**Automation Rule Triggered**](/api/webhooks#tag/events_schema_automation_rule_triggered): generated by manual tasks in Ivy
* [**Automation Trigger Webhook**](/api/webhooks): generated either manually or automatically by new automation feature in epilot 360
### Payload configuration

Customizing the payload of an incoming webhook request is entirely feasible. The standard structure for this customization typically follows this general format:

## Create Webhook
To secure your client server connection, please setup your webhook using endpoints supporting encryption, preferably [TLS](https://en.wikipedia.org/wiki/HTTPS). So we ensure encrypted data transfer to your server.
An easy way to create webhook is to use the webhook ui in the epilot portal. You can set up your webhook configuration using the management form, and fill in there details about the webhook endpoint, event types and [authorization information](#section/Create-webhook/Authentication). However you still can use our API in the same way.
To subscribe to an event using the API please use the `/v1/webhooks/configs` endpoint and post your receiver endpoint settings:

| field | Required | Description |
| ------- | --------| --------|
| eventName | required | epilot event you want to subscribe. see [Which events are available](#section/Create-Webhook/Which-events-are-available)|
| url | required | your endpoint where you want to receive the payload |
| httpMethod | required | http method |
| enabled | optional |boolean whether the webhook is active or not |
| auth | required |your endpoint authentication information. See [Authentication](#section/Create-Webhook/Authentication)|
| filter | optional |filter options, here you have the possibility to filter events, by product categories for example |

## Authentication
We assume that your event handler endpoint is secured, we support currently following authentication types:
* [Basic authentication](#section/Create-Webhook/Authentication/Basic-Authentication)
* [Oauth](#section/Create-Webhook/Authentication/Oauth)
* [API key](#section/Create-Webhook/Authentication/API-key)

Further details on how to set up your authentication information using the API:
### Basic Authentication

If you are using basic authentication you can set up the `auth` field

| field | Required | Description |
| ------- | --------| --------|
| authType | required | "BASIC" |
| basicAuthConfig | required | object only if authType is BASIC |

**basicAuthConfig**:

| field | Required | Description |
| ------- | --------| --------|
| username | required | valid username for your endpoint |
| password | required | password |

### OAuth

In case your endpoint is secured using Oauth your `Auth` should have following structure:

| field | Required | Description |
| ------- | --------| --------|
| authType | required | "OAUTH_CLIENT_CREDENTIALS" |
| oauthConfig | required | object only if authType is OAUTH_CLIENT_CREDENTIALS |

**oauthConfig**:

| field | Required | Description |
| ------- | --------| --------|
| clientId | required | your app Oauth client Id |
| clientSecret | required | Oauth client secret |
| endpoint | required | HTTPS endpoint for authentication |
| httpMethod | required | HTTP methods like GET, POST... |

### API key

We support also endpoints secured using API keys. In this case your webhook set up could be configured this way:

| field | Required | Description |
| ------- | --------| --------|
| authType * | "API_KEY" |
| apiKeyConfig * | object only if authType is API_KEY |

**apiKeyConfig**:

| field | Required | Description |
| ------- | --------| --------|
| keyName | required | used key name |
| keyValue | required | value of the used key |

## Enable Filtering

For better software integration you have the possibility to set up more granular filter for your subscribed events. For this please make use of the filter option when you create a webhook.
Please note that the entire event will be sent when the filter matches.

Using our ui in epilot portal, you can enable the filter option, and select items to be filtered.

Using the webhook API, here more details about the possible and required fields.

| field | Required | Description |
| ------- | --------| --------|
| keyToFilter | required | field of payload you want to filter |
| supportedValues | required | list of values you want to receive |

The subscribed events are simply a json structure, to have a filter in place for specific field in the event, you just set the `keyToFilter` value to be the field attribute structure of the json.

For example you have the following event structure and you want your filter to apply only auth type :

```
keyToFilter: {
id,
name,
security {
auth {
type // basic|apikey|oauth|none
}
}
```json
{
metadata: {
organization_id: '',
...
}, // always present
entity: {} // always present,
relations: {} // optional,
activity: {} // optional,
changedAttributes: {
added: {},
deleted: {},
updated: {}
} // optional
}
```
- Include Changed Attributes
- shows the ***changed*** added|deleted|updated attributes ***after*** the event
- Include Activity
- Include Relations
- **hydrated** relations to other entities
- important note: including this can increase the payload size significantly

the `keyToFilter` should be `keyToFilter.security.auth`. And possible values should be set in `supportedValues` field.

Please note that the `supportedValues` are **case sensitive**.

Following example will filter this sample event to send only events having auth types basic and oauth.

```
filter: {
keyToFilter: 'keyToFilter.security.auth',
supportedValues: ['basic', 'oauth']
}
```

**Sample filter:**

For `Customer request` event you can filter events and receive only events related to specific product category:
```
filter: {
keyToFilter: 'customer_request.request_items.product_category',
supportedValues: ['solar', 'electricity']
}
```

## List configured webhooks

The `/v1/webhooks/configs` endpoint provides the list of the configured webhooks by your organization in following structure:

| field | Description |
| ------- | --------|
|id | webhook id |
|eventName |subscribed event name|
|url | configured client endpoint Url|
|creationTime| webhook creation time|
|httpMethod | configured http method|
|enabled | boolean whether the webhook is enabled or not|
|auth | Auth settings if set|
|filter | filter settings if set|

## Delete webhook

To delete configured webhook using the ui, just hit the delete button for the wanted webhook configuration.
To delete a webhook configuration using the API please use the `/v1/webhooks/configs/{WebhookId}` endpoint with `DELETE` http call.
![Custom Webhook Payload Configuration](../static/img/webhook-custom-payload.png)

After deleting a webhook configuration you are still able to fetch failed and successfully sent events related to the deleted configuration.
### Custom oauth parameter

To retrieve webhook id you can query the configured webhooks, see [List configured Webhooks](#section/List-configured-Webhooks).
Custom OAuth parameters can be seamlessly integrated into the webhook configuration process. These parameters can be included as part of the OAuth request, appended as body, query, or header parameters. This feature empowers users to augment the OAuth request with supplementary information as needed, enhancing the flexibility and customization options within the authentication flow.

## Edit Webhook
![Custom Webhook Ouath Parameter](../static/img/webhook-custom-oauth.png)

Using the ui in the epilot portal you can very easily edit a webhook config. You will be asked to edit the pre filled form.
To update a webhook configuration using the API please use following endpoint `/v1/webhooks/configs/{WebhookId}` using `PUT` http method.
To retrieve webhook id you can query the configured webhooks, see [List configured Webhooks](#section/List-configured-Webhooks).

Additional to this path parameters, the payload to update the webhook configuration is the same we use for creating new webhooks. You can also refer to [Which events are available](#section/Create-Webhook) for more details.
# Limitations

To deactivate or reactivate a webhook configuration, you can make use of this endpoint, providing the organization id and webhook id as path parameter, and your payload should contain same configuration saved except the field `enabled` should either `false` if you want to deactivate the webhook otherwise `true` if the webhook should be active.
## Timeout
The maximum allowable duration for a request is 5 seconds. Should the request exceed this time limit, it will be automatically aborted, prompting the webhook to retry the request up to 2 times. If, after these retries, the request continues to fail, the webhook will be flagged as unsuccessful.
Binary file added static/img/webhook-custom-oauth.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/webhook-custom-payload.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit d017f7d

Please sign in to comment.