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