With the webhook integration, you can now receive notifications about updates to your reports directly within the tools used by your organisation. Activate or deactivate events such as “new report”, “new comment”, “assessment” or "report status" in the webhook configuration to automatically receive notifications when these events occur.

How to configure a webhook integration?

ℹ️ You must be a Business Unit Owner or a Business Unit Manager to configure a webhook integration.

⚠️ Notes:

A webhook is configured at the Business Unit level.
You must have at least one program in your Business Unit to configure a webhook.
A business unit can only have one webhook integration at a time.

Go to the “Admin panel”
Click on “Integrations” in the left-side menu
Select the “Webhook notifications” tab
Click on “Configure”

Fill in the webhook URL

⚠️ The provided URL must be in HTTPS.

Select which events you want to receive notifications for.

Below is the list of existing events. These events are described in the webhook-Event HTTP header.

EVENT	DESCRIPTION	WEBHOOK EVENT
New report	When a new report has been submitted	`report_new`
Comment	When a new comment has been submitted	`report_comment`
Triage assessment	When the report has been assessed by triagers	`report_assessment`
Report status update	When a report status has been updated (eg., new>under_review)	`report_status`
Test event	When receiving a test event when testing a webhook configuration	`ywh.test_configuration`

Click on “Configure”

The webhook is now configured at the Business Unit level.

ℹ️ Notes

An existing configuration can be modified using the “Edit configuration” button.
Click “Delete configuration” to remove the webhook integration.

Verify your signature

When you configure a webhook, a secret is automatically generated to help you verify the signature of incoming webhook requests. You can edit this secret during configuration. This secret is used in every webhook request to generate a signature that can be verified by your application.

The signature is an HMAC-SHA256 hash, computed as follows:

HMAC-SHA256(key = your webhook secret, message = event_name + event_id + raw_request_body)

The three elements are concatenated in that exact order, with no separator.
raw_request_body is the request body exactly as sent (raw JSON) not Base64-encoded.
The secret is used as a plain ASCII string, not decoded.

The result is sent in the Webhook-Signature HTTP header as sha256=<hex-encoded HMAC>.

Example (Python):

import hashlib
import hmac


def verify_yeswehack_webhook_signature(
    raw_body: bytes,
    event_name: str,
    event_id: str,
    signature_header: str,
    secret: str,
) -> bool:
    if not signature_header.startswith("sha256="):
        return False

    signed_payload = event_name.encode("utf-8") + event_id.encode("utf-8") + raw_body

    expected_signature = hmac.new(
        secret.encode("utf-8"),
        signed_payload,
        hashlib.sha256,
    ).hexdigest()

    received_signature = signature_header.removeprefix("sha256=")

    return hmac.compare_digest(expected_signature, received_signature)

#Important note: raw_body must be exactly the raw body received (e.g., request.get_data())

⚠️ You must use the same secret in both the YWH platform and your organisation's tool for the integration to work.

Payload example

Regardless of which event you receive (report_new, report_comment, report_assessment or report status) the JSON body has the exact same structure:

{
   "schema_version": 1,
   "timestamp": "2026-08-11T10:15:30+00:00",
   "author_type": "hunter",
   "resource": {
     "type": "report",
     "report_id": 123456,
     "severity": "high",
     "suggested_severity": "critical"
   },
   "context": {
     "program_slug": "example-corp"
   }
 }

author_type : hunter, triager, manager or system
severity / suggested_severity : none, low, medium, high, critical
timestamp: ISO 8601 date-time (e.g. 2026-08-11T10:15:30+00:00) representing when the underlying action occurred on the YesWeHack platform (report submission, comment, assessment, or status update) not when the HTTP request was sent. Due to retries and queuing, actual delivery may happen a few seconds after this timestamp.

Error message

If a webhook delivery fails for technical reasons, it is retried automatically up to 3 times, with an increasing delay between attempts (2 seconds, then 4 seconds, then 8 seconds). If all attempts fail, an error message is displayed.

⚠️ Your endpoint must respond with an HTTP status code in the 2xx range to acknowledge a received event. Any other status code (redirects included) is treated as a delivery failure and triggers a retry.

Several issues may prevent the webhook integration from being configured:

An issue on the customer side related to the request (e.g., 400 Bad Request),
An issue on the server side (e.g., 500 Internal Server Error),
An HTTP redirect returned by your endpoint. Redirects are never followed.
A timeout issue (e.g., the page does not load correctly).

ℹ️ If you cannot identify the cause of an error message, please contact your CSM for assistance with the webhook configuration.

Delivery guarantees

Webhook events are delivered at least once. After a failed delivery, the event is retried (see above) your endpoint should be able to safely handle receiving the same underlying event more than once.
The Webhook-Id header is not stable across retries: each delivery attempt generates a new Webhook-Id and a new signature. It cannot be used to detect duplicates, use the payload content instead (e.g. resource.report_id combined with timestamp).
Ordering is not guaranteed. Events may be delivered out of order (for example, if an earlier event is delayed by a retry while a later one succeeds first). If your integration depends on ordering, sort incoming events using the timestamp field rather than their arrival order.

Verify your integration

if you have configured a webhook integration and want to ensure it works correctly, manually test your webhook configuration to confirm it is functional.

Click on “Test configuration”

A new window will open to inform you that the verification is currently in progress.

⚠️ Do not close this window during the webhook configuration verification.

Your webhook will receive an event with an empty body:

Content-Type: application/json
Webhook-Event: ywh.test_configuration 
Webhook-Id: $id 
Webhook-Signature: sha256=$signature 

[]

First case: the verification succeeded. You can close the window.

If the configuration cannot be validated, an error message is displayed. Update your configuration to complete the process.

Webhook integration