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.