Event Webhook Explained

Event webhooks allow integrating Shipa events with external systems.

You can create webhooks to notify users of the occurrence of specific types of events. Shipa 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.

shipa event webhook list

Creating Webhooks

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

shipa 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 Shipa, 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:

shipa 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:

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

Updating Webhooks

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

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

shipa event webhook delete <name>

Did this page help you?