Skip to main content

Rule Builder: Webhooks

dave herder
  • Updated

In this article:

     

    What are webhooks and when should they be used?

    Webhooks are automated messages sent from apps when something happens. They have a message—or payload—and are sent to a unique URL—essentially the app’s phone number or address.

    They are ideal for integrations where:

    • You want to react to any type of scorecard changes, without having to continuously fetch and compare scorecard data (avoid unnecessary polling)
    • You want to include custom logic in the workflow on a Rule
    • You want to connect events in SecurityScorecard with workflows in other tools or infrastructure in your organization

    How to create Rules with webhooks

    • Name your Rule
    • Select the event for which you would like to trigger the action
    • Select the group of Scorecards your rule will apply to
      • My Scorecard
      • All Followed Scorecards
      • Selected Portfolio
    • Select Send Web Request as the action

    Read our article on Rule Builder for further details.

    What to expect from SecuritySecurityScorecard?

    • Expect to receive a POST request with JSON as the request body
    • JSON fields:
      • scorecard_id: id of the scorecard involved in the event
      • domain: scorecard domain
      • trigger: an object containing information about what triggered the rule execution
      • execution_id: an unique identifier for this execution, if webhook call should be retried the execution_id will be the same on each retry
      • created_at: timestamp when this execution was created (first execution attempt)
      • retries: if the webhook already failed this is the amount of retries been performed
      • webhooks: if there are previous steps in the rule where other webhooks have been called, here are an array of each called webhook url and its response

    Retries, Timeouts, etc.

    • Retries

      • We will retry 5 times during 36 hours. After 36 hours, we will escalate with the Rule owner

        • When escalated the Rule owner will recieve an email

          • Expect the following email:

            Subject: [Action Required] Failed Webhook Request
Your webhook requests for the Rule <X> have failed due to a network or destination server issue. We'll try again the next time a rule is triggered.                   Please try one of the following:
       * Edit the Rule to have the web request sent to a different URL
       * Check your service internally or credentials for service availability
       Details:
       Failed Rule: <X>
       Webhook URL:  <X>
       HTTP error:  <X>

      • We will call the webhook and wait for a limited time before terminating the call

        • Time limit: 5 seconds
    • Response size limit
      • We will support a response size no greater than 100KB
    • Response status codes that we expect you to support in order to to determine the success or failure of the webhook request
      • Success status codes: 20x
      • Failure status codes: 40x, 50x

    Read our webhook guide for additional information.

    Related articles