Webhook Implementation Documentation
## Introduction**Introduction**
This document provides technical details for integrating your system with our webhook service. The webhook operates over SSL and requires a bearer token for authentication. Once set up, it will send all scan results to your specified endpoint in real-time.
## **Table of ContentsContents**
1. [Overview](#overview)Overview
2. [Prerequisites](#prerequisites)Prerequisites
3. [Authentication](#authentication)Authentication
4. [Setting Up the Webhook](#setting-up-the-webhook)Webhook
5. [Data Format](#data-format)Format
6. [Security Considerations](#security-considerations)Considerations
7. [Error Handling](#error-handling)
Handling
---
## Overview**Overview**
Our webhook service enables seamless integration by sending scan results directly to your application's endpoint. Communication is secured using SSL/TLS encryption, and access is controlled via a bearer token that you provide.
## Prerequisites**Prerequisites**
- **HTTPS Endpoint**:Endpoint: An SSL-enabled endpoint capable of receiving HTTP POST requests.
- **Bearer Token**:Token: A secure token for authenticating requests (you must generate and provide this token).
- **JSON Parsing**:Parsing: Ability to parse JSON-formatted data in your application.
## Authentication**Authentication**
All webhook requests include a bearer token in the `Authorization`Authorization header for security.
- **Header Format**:
- Replace `YOUR_BEARER_TOKEN`"YOUR_BEARER_TOKEN" with the token you have generated.
## **Setting Up the WebhookWebhook**
1. **Provide Endpoint URL**:URL: Supply us with your HTTPS endpoint URL where you wish to receive the scan results.
2. **Generate Bearer Token**:Token: Create a secure, random token for authentication purposes.
3. **Configure Firewall**:Firewall: Ensure that your server accepts incoming connections from our IP addresses (contact support for the IP range if necessary).
4. **Test the Connection**:Connection: Verify that your endpoint correctly handles incoming POST requests.
## **Data FormatFormat**
Scan results are sent as JSON in the body of a POST request.
- **Example Request**:Request:
```http
POST /your-endpoint HTTP/1.1
Host: yourdomain.com
Content-Type: application/json
Authorization: Bearer YOUR_BEARER_TOKEN
{
"scanId": "abc123",
"status": "completed",
"results": {
"threatsFound": 0,
"details": []
},
"timestamp": "2023-10-23T14:55:00Z"
}
```
- **JSON Fields**:Fields:
- `scanId`:scanId: Unique identifier for the scan.
- `status`:status: Current status of the scan (`"completed"`, `"in_progress"`, `"failed"`).
- `results`:results: Object containing the scan results.
- `threatsFound`:threatsFound: Number of threats detected.
- `details`:details: Array with detailed information on each threat.
- `timestamp`:timestamp: ISO 8601 timestamp of when the scan was performed.
## **Security ConsiderationsConsiderations**
- **SSL/TLS Encryption**:Encryption: All data is transmitted over HTTPS to ensure encryption in transit.
- **Bearer Token Confidentiality**:Confidentiality: Keep your bearer token secure; do not expose it in client-side code or logs.
- **Input Validation**:Validation: Validate and sanitize all incoming data on your server.
- **Rate Limiting**:Limiting: Implement rate limiting if necessary to protect against denial-of-service attacks.
## **Error HandlingHandling**
- **Successful Processing**:Processing:
- Return HTTP status code `200 OK`.
- Optionally, include a JSON response acknowledging receipt.
```json
{
"message": "Scan results received successfully."
}
```
- **Authentication Failure**:Failure:
- Return HTTP status code `401 Unauthorized`.
- Include an error message indicating invalid authentication.
- **Other Errors**:Errors:
- Return appropriate HTTP status codes (`400 Bad Request`, `500 Internal Server Error`, etc.).
- Include a JSON object with an `error`error field describing the issue.