Webhook Integration Guide

1. How Webhooks Work

Webhooks provide a real-time integration mechanism that pushes event data from SPScan to your systems as events occur. When an alert rule is triggered and the target channel is a webhook, SPScan sends an HTTP POST request to your configured URL with a JSON payload describing the event. This push-based approach is more efficient than polling the API because your system only receives data when something happens.

Webhook delivery is asynchronous and runs on the alerts queue. When an event matches one of your alert rules, SPScan constructs the payload, sends the POST request, and records the delivery result. If your endpoint returns a 2xx status code, the delivery is marked as successful. If the request fails or returns an error status code, SPScan will retry the delivery with exponential backoff.

Webhooks are ideal for integrating SPScan with ticketing systems, custom dashboards, Slack bots, security information and event management (SIEM) platforms, and any other system that can receive HTTP requests. Because the payload is structured JSON, it is straightforward to parse and process in any programming language.

2. Setting Up a Webhook Channel

To create a webhook alert channel, navigate to the Alerts section from any tenant's sidebar and click on "Channels". Click "Add Channel" and select "Webhook" as the channel type. Enter a descriptive name for the channel and the URL of your webhook endpoint. The URL must be publicly accessible and capable of receiving POST requests with a JSON body.

Your webhook endpoint should respond with a 2xx HTTP status code to acknowledge receipt of the payload. SPScan does not require any specific response body, only the status code matters for delivery confirmation. If your endpoint needs time to process the payload, return a 202 Accepted immediately and process the data asynchronously in your own system.

After creating the channel, use the "Test" button to send a sample payload to your endpoint. This verifies that your URL is reachable, your endpoint is accepting POST requests, and it returns a successful status code. The test payload has the same structure as real event payloads, so you can use it to validate your parsing logic before real events are generated.

3. Payload Structure

Every webhook payload follows a consistent JSON structure. The top-level object includes an event field indicating the type of event (such as "permission.external_share_created" or "storage.threshold_exceeded"), a timestamp field with the ISO 8601 date and time, and a tenant object with the affected tenant's details.

The tenant object includes the tenant's SPScan ID, display name, and Microsoft tenant ID. The data object contains event-specific details that vary by event type. For permission events, it includes the site URL, resource path, permission type, principal, and access level. For storage events, it includes the site URL, current usage, quota, and the threshold that was exceeded.

The payload also includes a severity field (low, medium, high, or critical) and a unique event_id that you can use for deduplication. If you receive the same event_id more than once due to a retry, you can safely ignore the duplicate. This idempotency mechanism ensures that retries do not cause duplicate processing in your system.

4. Handling Webhook Delivery

SPScan retries failed webhook deliveries using exponential backoff. If the first delivery attempt fails, SPScan waits 30 seconds before the first retry, then 2 minutes, then 10 minutes, for a total of three retry attempts. If all attempts fail, the delivery is marked as failed and recorded in the alert logs. You can view failed deliveries on the alert logs page to diagnose issues.

Common causes of delivery failures include network timeouts, DNS resolution errors, SSL certificate issues, and endpoints returning non-2xx status codes. Make sure your endpoint has a valid SSL certificate, responds within 30 seconds, and returns a 200 or 202 status code. If your endpoint requires authentication, you will need to handle that within your application logic since SPScan sends unauthenticated POST requests.

For high-reliability integrations, we recommend implementing your webhook endpoint as a thin receiver that acknowledges receipt immediately and queues the payload for asynchronous processing. This approach minimises the risk of timeouts and ensures that SPScan always receives a timely acknowledgement. You can then process the payloads at your own pace without worrying about delivery failures.

5. Example Integrations

One of the most popular webhook integrations is creating custom Slack notifications with enriched formatting. Instead of using SPScan's built-in Slack channel, you can point a webhook at your own middleware that receives SPScan events, enriches them with additional context from your own systems (such as client name or account manager), and posts a richly formatted message to Slack using the Slack API.

Another common integration is creating tickets in your service desk or ticketing system. When SPScan detects a high-severity permission change, your webhook endpoint can automatically create a ticket in tools like ConnectWise, Autotask, Jira, or ServiceNow. The ticket can include all the relevant details from the webhook payload, pre-assigned to the appropriate team or technician based on the affected tenant.

For organisations with a SIEM platform, webhooks provide a straightforward way to feed SharePoint permission events into your security event pipeline. Forward the webhook payloads to your SIEM's HTTP event collector, and you can correlate SharePoint permission changes with other security events across your infrastructure. This gives your security analysts a unified view of potential threats across all of your monitored systems.