Webhooks

Event Webhook Explained

Event webhooks allow integrating Lens AppIQ Events with external systems.

You can create webhooks to notify users of the occurrence of specific types of events. Lens AppIQ requests the specified URL for every event according to specific filters defined when users create an event webhook.

Event webhook configurations basically involve filtering events and configuring the hook request.

Event Filtering

By default, all events that the webhook creator has access to can be triggered, but certain criteria may filter events:

Error only: triggers only failing events
Success only: triggers only successful events
Kind type: is either permission or internal
Kind name: is one of the values returned by the permission list command, like app.create or framework.update
Target type: can be global, app, node, container, framework, service, service-instance, team, user, iaas, role, platform, plan, node-container, install-host, event-block, cluster, volume, or webhook
Target value: is the value according to the target type. When the target type is an app, for instance, the target value is the app name

Hook Requests

URL: is the URL of the request
Method: can be GET, POST, PUT, PATCH, or DELETE. Defaults to POST
Headers: are the HTTP headers, defined in key=value format
Body: is the request's payload, used when the method is POST, PUT, or PATCH. Defaults to the serialized event in JSON
Proxy: is the proxy server used for the requests

You can use Go templates to specify the body request and use event fields as variables.

type eventData struct {
    ID              eventID `bson:"_id"`
    UniqueID        bson.ObjectId
    StartTime       time.Time
    EndTime         time.Time     `bson:",omitempty"`
    Target          Target        `bson:",omitempty"`
    ExtraTargets    []ExtraTarget `bson:",omitempty"`
    StartCustomData bson.Raw      `bson:",omitempty"`
    EndCustomData   bson.Raw      `bson:",omitempty"`
    OtherCustomData bson.Raw      `bson:",omitempty"`
    Kind            Kind
    Owner           Owner
    LockUpdateTime  time.Time
    Error           string
    Log             string    `bson:",omitempty"`
    RemoveDate      time.Time `bson:",omitempty"`
    CancelInfo      cancelInfo
    Cancelable      bool
    Running         bool
    Allowed         AllowedPermission
    AllowedCancel   AllowedPermission
}

You can find detailed information through the sections below:

Listing Webhooks

To list existing webhooks, use the event webhook list command.

lapps event webhook list

Creating Webhooks

To create a new webhook that triggers when an event matches those specified, use the event webhook create command.

lapps event webhook create <name> <url> [-d/--description <description>] [-t/--team <team>] [-m/--method <method>] [-b/--body <body>] [--proxy <url>] [-H/--header <name=value>]... [--insecure] [--error-only] [--success-only] [--target-type <type>]... [--target-value <value>]... [--kind-type <type>]... [--kind-name <name>]...

Flags:

Flag	Description
-H, --header	(= {}) The HTTP headers sent in the request
-b, --body	(= "") The HTTP body sent in the request. The method is either POST, PUT, or PATCH. If unset, it defaults to the Event that triggered the webhook serialized as JSON. The API will try to parse the body as a Go template string with the event available as context.
-d, --description	(= "") A description of how the webhook will be used
--error-only	(= false) Only matches events with error
--insecure	(= false) Ignore TLS errors in the webhook request
--kind-name	(= []) Kind Name for matching events
--kind-type	(= []) Kind Type for matching events
-m, --method	(= "") The HTTP method used in the request. If unset, it defaults to POST
--proxy	(= "") The proxy server URL used in the request. Supported schemes are HTTP(s) and socks5.
--success-only	(= false) Only matches events with success
-t, --team	(= "") The team name responsible for this webhook
--target-type	(= []) Target Type for matching events
--target-value	(= []) Target Value for matching events

Example 1: Slack Alerts

🚧
Slack Configuration
Before creating the webhook on Lens AppIQ make sure webhooks are enabled and configured on your Slack account.
For more information, please visit the Slack Webhooks page.

To notify every successful app deployment to a Slack channel:

lapps event webhook create slack https://hooks.slack.com/services/SHIPA/SHIPA/ShipaShipaShipa -d "all successful deploys" -t admin -m POST -H Content-Type=application/json -b '{"text": "{{.Kind.Name}}: {{.Target.Type}} {{.Target.Value}}"}' --kind-name app.deploy

Using the event webhook above produces a result similar to the one below:

Example 2: Calling External URLs

Calling a specific URL every time a specific app is updated:

lapps event webhook create my-webhook <my-url>
        -t <my-team>
        --kind-name app.update
        --target-value <my-app>

Example 3: Microsoft Team Alerts

📘
Teams Configuration
Microsoft Teams will require the Incoming Webhooks Application installed in MS Teams. Here is a Shipa Blog going through step by step: https://shipa.io/development/first-shipa-webhook/

To notify every successful app deployment to a Teams channel:

lapps event webhook create msteams https://self260.webhook.office.com/webhookb2/****** -d "Application Deployments" -t shipa-team -m POST -H Content-Type=application/json -b '{"text": "{{.Kind.Name}}: {{.Target.Type}} {{.Target.Value}}"}' --kind-name app.deploy

Using the event webhook above produces a result similar to the one below:

Updating Webhooks

To update existing webhooks, use the event webhook update command.

lapps event webhook update <name> [-u/--url <url>] [-d/--description <description>] [-t/--team <team>] [-m/--method <method>] [-b/--body <body>] [--proxy <url>] [-H/--header <name=value>]... [--insecure] [--error-only] [--success-only] [--target-type <type>]... [--target-value <value>]... [--kind-type <type>]... [--kind-name <name>]... [--no-body] [--no-header] [--no-insecure] [--no-target-type] [--no-target-value] [--no-kind-type] [--no-kind-name] [--no-error-only] [--no-success-only]

Flags:

Flag	Description
-H, --header	(= {}) The HTTP headers sent in the request
-b, --body	(= "") The HTTP body sent in the request. The method is either POST, PUT, or PATCH. If unset, it defaults to the Event that triggered the webhook serialized as JSON. The API will try to parse the body as a Go template string with the event available as context.
-d, --description	(= "") A description on how the webhook will be used.
--error-only	(= false) Only matches events with error
--insecure	(= false) Ignore TLS errors in the webhook request
--kind-name	(= []) Kind Name for matching events
--kind-type	(= []) Kind Type for matching events
-m, --method	(= "") The HTTP method used in the request. If unset, it defaults to POST
--no-body	(= false) Unset body value
--no-error-only	(= false) Unset only matches events with error
--no-header	(= false) Unset header value
--no-insecure	(= false) Unset insecure value
--no-kind-name	(= false) Unset Kind Name for matching events
--no-kind-type	(= false) Unset Kind Type for matching events
--no-success-only	(= false) Unset only matches events with success
--no-target-type	(= false) Unset Target Type for matching events
--no-target-value	(= false) Unset Target Value for matching events
--proxy	(= "") The proxy server URL used in the request. Supported schemes are HTTP(s) and socks5.
--success-only	(= false) Only matches events with success
-t, --team	(= "") The team name responsible for this webhook
--target-type	(= []) Target Type for matching events
--target-value	(= []) Target Value for matching events
-u, --url	(= "") The HTTP URL used in the request

Deleting Webhooks

To delete webhooks, use the event webhooks delete command.

lapps event webhook delete <name>