webhook/docs/Hook-Rules.md

Hook rules

Table of Contents

• And
• Or
• Not
• Multi-level
• Match
  • Match value
  • Match regex
  • Match payload-hmac-sha1
  • Match payload-hmac-sha256
  • Match payload-hmac-sha512
  • Match Whitelisted IP range
  • Match scalr-signature

And

And rule will evaluate to true, if and only if all of the sub rules evaluate to true.

{
"and":
  [
    {
      "match":
      {
        "type": "value",
        "value": "refs/heads/master",
        "parameter":
        {
          "source": "payload",
          "name": "ref"
        }
      }
    },
    {
      "match":
      {
        "type": "regex",
        "regex": ".*",
        "parameter":
        {
          "source": "payload",
          "name": "repository.owner.name"
        }
      }
    }
  ]
}

Or

Or rule will evaluate to true, if any of the sub rules evaluate to true.

{
"or":
  [
    {
      "match":
      {
        "type": "value",
        "value": "refs/heads/master",
        "parameter":
        {
          "source": "payload",
          "name": "ref"
        }
      }
    },
    {
      "match":
      {
        "type": "value",
        "value": "refs/heads/development",
        "parameter":
        {
          "source": "payload",
          "name": "ref"
        }
      }
    }
  ]
}

Not

Not rule will evaluate to true, if and only if the sub rule evaluates to false.

{
"not":
  {
    "match":
    {
      "type": "value",
      "value": "refs/heads/development",
      "parameter":
      {
        "source": "payload",
        "name": "ref"
      }
    }
  }
}

Multi-level

{
    "and": [
    {
        "match": {
            "parameter": {
                "source": "header",
                "name": "X-Hub-Signature"
            },
            "type": "payload-hmac-sha1",
            "secret": "mysecret"
        }
    },
    {
        "or": [
        {
            "match":
            {
                "parameter":
                {
                    "source": "payload",
                    "name": "ref"
                },
                "type": "value",
                "value": "refs/heads/master"
            }
        },
        {
            "match":
            {
                "parameter":
                {
                    "source": "header",
                    "name": "X-GitHub-Event"
                },
                "type": "value",
                "value": "ping"
            }
        }
        ]
    }
    ]
}

Match

Match rule will evaluate to true, if and only if the referenced value in the parameter field satisfies the type-specific rule.

Please note: Due to technical reasons, number and boolean values in the match rule must be wrapped around with a pair of quotes.

Match value

{
  "match":
  {
    "type": "value",
    "value": "refs/heads/development",
    "parameter":
    {
      "source": "payload",
      "name": "ref"
    }
  }
}

Match regex

For the regex syntax, check out http://golang.org/pkg/regexp/syntax/

{
  "match":
  {
    "type": "regex",
    "regex": ".*",
    "parameter":
    {
      "source": "payload",
      "name": "ref"
    }
  }
}

Match payload-hmac-sha1

Validate the HMAC of the payload using the SHA1 hash and the given secret.

{
  "match":
  {
    "type": "payload-hmac-sha1",
    "secret": "yoursecret",
    "parameter":
    {
      "source": "header",
      "name": "X-Hub-Signature"
    }
  }
}

Note that if multiple signatures were passed via a comma separated string, each will be tried unless a match is found. For example:

X-Hub-Signature: sha1=the-first-signature,sha1=the-second-signature

Match payload-hmac-sha256

Validate the HMAC of the payload using the SHA256 hash and the given secret.

{
  "match":
  {
    "type": "payload-hmac-sha256",
    "secret": "yoursecret",
    "parameter":
    {
      "source": "header",
      "name": "X-Signature"
    }
  }
}

Note that if multiple signatures were passed via a comma separated string, each will be tried unless a match is found. For example:

X-Hub-Signature: sha256=the-first-signature,sha256=the-second-signature

Match payload-hmac-sha512

Validate the HMAC of the payload using the SHA512 hash and the given secret.

{
  "match":
  {
    "type": "payload-hmac-sha512",
    "secret": "yoursecret",
    "parameter":
    {
      "source": "header",
      "name": "X-Signature"
    }
  }
}

Note that if multiple signatures were passed via a comma separated string, each will be tried unless a match is found. For example:

X-Hub-Signature: sha512=the-first-signature,sha512=the-second-signature

Match Whitelisted IP range

The IP can be IPv4- or IPv6-formatted, using CIDR notation. To match a single IP address only, use /32.

{
  "match":
  {
    "type": "ip-whitelist",
    "ip-range": "192.168.0.1/24"
  }
}

Note this does not work if webhook is running behind a reverse proxy, as the "client IP" will either not be available at all (if webhook is using a Unix socket or named pipe) or it will be the address of the proxy, not of the real client. You will probably need to enforce client IP restrictions in the reverse proxy itself, before forwarding the requests to webhook.

Match scalr-signature

The trigger rule checks the scalr signature and also checks that the request was signed less than 5 minutes before it was received. A unique signing key is generated for each webhook endpoint URL you register in Scalr. Given the time check make sure that NTP is enabled on both your Scalr and webhook server to prevent any issues

{
  "match":
  {
    "type": "scalr-signature",
    "secret": "Scalr-provided signing key"
  }
}