Skip to main content

Webhooks

[API Docs] [SDK]

The epilot Webhooks API 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.

This document describes the steps how to configure hooks, subscribe to events and how to manage those configurations. Service is reachable using https connection to ensure encryption between client and service.

Webhooks can be comfortably configured and managed by admin users in epilot portal.

Webhooks API Documentation

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.

In Events Schemas section you find the schemas of available events ready to register:

Create Webhook

To secure your client server connection, please setup your webhook using endpoints supporting encryption, preferably TLS. 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. 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:

fieldRequiredDescription
eventNamerequiredepilot event you want to subscribe. see Which events are available
urlrequiredyour endpoint where you want to receive the payload
httpMethodrequiredhttp method
enabledoptionalboolean whether the webhook is active or not
authrequiredyour endpoint authentication information. See Authentication
filteroptionalfilter 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:

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

fieldRequiredDescription
authTyperequired"BASIC"
basicAuthConfigrequiredobject only if authType is BASIC

basicAuthConfig:

fieldRequiredDescription
usernamerequiredvalid username for your endpoint
passwordrequiredpassword

OAuth

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

fieldRequiredDescription
authTyperequired"OAUTH_CLIENT_CREDENTIALS"
oauthConfigrequiredobject only if authType is OAUTH_CLIENT_CREDENTIALS

oauthConfig:

fieldRequiredDescription
clientIdrequiredyour app Oauth client Id
clientSecretrequiredOauth client secret
endpointrequiredHTTPS endpoint for authentication
httpMethodrequiredHTTP 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:

fieldRequiredDescription
authType *"API_KEY"
apiKeyConfig *object only if authType is API_KEY

apiKeyConfig:

fieldRequiredDescription
keyNamerequiredused key name
keyValuerequiredvalue 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.

fieldRequiredDescription
keyToFilterrequiredfield of payload you want to filter
supportedValuesrequiredlist 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
}
}
}

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:

fieldDescription
idwebhook id
eventNamesubscribed event name
urlconfigured client endpoint Url
creationTimewebhook creation time
httpMethodconfigured http method
enabledboolean whether the webhook is enabled or not
authAuth settings if set
filterfilter 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.

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

To retrieve webhook id you can query the configured webhooks, see List configured Webhooks.

Edit Webhook

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.

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 for more details.

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.