# Test Webhook Endpoint

The Test Webhook endpoint allows customers to send a sample test payload to a given URL to verify its connectivity and signature validation logic before creating a webhook configuration. This helps ensure your webhook handler is working correctly.

## Authentication

Include the following headers in your requests:

```
Access-Token: <your-access-token>
```

## Permissions

Ensure your API user has a role with `admin` or `test-alert-webhook-endpoint` permission.

## Endpoint

- **URL**: `https://api.genlogs.io/alerts/webhook/test`
- **Method**: `POST`

## Request Body

| Field      | Type   | Required | Description                                                   |
|------------|--------|----------|---------------------------------------------------------------|
| `webhook_url` | string | Yes      | The HTTPS URL to send the test payload to                    |
| `secret`   | string | Yes      | The secret that will be used to sign the test payload        |

## Request example

```
curl --location 'https://api.genlogs.io/alerts/webhook/test' \
--header 'access-token: <access-token>' \
--header 'x-api-key: <x-api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "webhook_url": "https://example-host.com/webhooks/genlogs-alerts",
    "secret": {your-webhook-secret}
}'
```

### Field Requirements

- **webhook_url**: Must be a valid HTTPS URL that can receive POST requests
- **secret**: Must be at least 16 characters long (same as used for webhook creation)

## Response Codes

| Code       | Description                                                  |
|------------|--------------------------------------------------------------|
| `200 OK`   | The test was sent successfully and your endpoint responded with a 2xx status code|
| `400 Bad Request` | The provided URL or secret is invalid                |
| `401 Unauthorized` | Authentication credentials missing or incorrect       |
| `403 Forbidden` | User lacks permission to test webhooks                  |
| `500 Internal Server Error` | The test failed (timeout, non-2xx response, connection error, etc.)|

## Response Body

### Success Response

| Field      | Type     | Description                     |
|------------|----------|---------------------------------|
| `success`  | boolean  | `true` if the test was successful|
| `status`   | integer  | HTTP status code (always `200` for successful tests)|
| `message`  | string   | Success confirmation message     |

### Error Response

| Field      | Type     | Description                                    |
|------------|----------|------------------------------------------------|
| `success`  | boolean  | `false` when the test failed                    |
| `status`   | integer  | HTTP status code (typically `500` for failed tests)|
| `message`  | string   | Error description explaining why the test failed|

## Test Payload Structure

The test endpoint sends a sample payload with the following structure to verify your webhook handler:

```
{
  "event": "alert.test",
  "webhook_id": "test-webhook-id",
  "customer_id": 123,
  "alert_details": [{
    "alert_name": "Test Alert",
    "email": "test@example.com",
    "description": "This is a test alert"
  }],
  "matches": [{
    "result_url": "https://app.genlogs.com/search/result/test",
    "front_view_url": "https://example.com/image1.jpg",
    "side_view_url": "https://example.com/image2.jpg",
    "rear_view_url": "https://example.com/image3.jpg",
    "time": "2024-01-01T12:00:00Z",
    "city": "Test City",
    "state": "TS",
    "road": "Test Road",
    "lat_long": "40.7128, -74.0060",
    "license_plate": "TEST123",
    "vin": "1HGBH41JXMN109186",
    "usdot": "123456",
    "mc": "MC-123456",
    "cab_number": "CAB123",
    "trailer_logo": "Test Logo",
    "trailer_number": "TRL123",
    "deep_search": "Test Match"
  }],
  "total_matches": 1,
  "timestamp": "2024-01-01T12:01:00.123456+00:00"
}
```

## Signature Validation Example

```
import hmac
import hashlib

def verify_signature(payload_body: bytes, signature_header: str, secret: str) -> bool:
    """Verifies the HMAC-SHA512 signature of a webhook payload."""
    if not signature_header:
        return False

hash_object = hmac.new(
        secret.encode('utf-8'),
        msg=payload_body,
        digestmod=hashlib.sha512
    )
    expected_signature = "sha512=" + hash_object.hexdigest()

return hmac.compare_digest(expected_signature, signature_header)

# Usage in your webhook handler
signature = request.headers.get('X-GenLogs-Signature')
payload_body = request.get_data()  # Raw bytes
webhook_secret = "your-super-secret-key-at-least-16-chars"

if verify_signature(payload_body, signature, webhook_secret):
    # Signature is valid, process the webhook
    payload = request.get_json()
    return {"status": "success"}, 200
else:
    # Invalid signature
    return {"error": "Invalid signature"}, 401
```

## What to Verify in Your Webhook Handler

When you receive the test payload, verify:

1. **Signature Verification**: Ensure you can properly verify the HMAC-SHA512 signature in the `X-GenLogs-Signature` header
2. **JSON Parsing**: Confirm you can parse the JSON payload correctly
3. **Response Time**: Respond within 5 seconds (the webhook timeout)
4. **HTTP Status**: Return a 2xx status code to indicate success
5. **Headers**: Check that you receive all expected headers:
   - `Content-Type: application/json`
   - `User-Agent: GenLogs-Webhook/1.0`
   - `X-GenLogs-Signature: sha512=...`
   - `X-GenLogs-Event: alert.test`
   - `X-GenLogs-Timestamp: ...`

## Common Test Failure Reasons

- **Connection timeout** (webhook endpoint not responding within 5 seconds)
- **Invalid SSL certificate** on the webhook URL
- **Non-2xx HTTP response** from your endpoint
- **Connection refused** (endpoint not accessible)
- **DNS resolution failure** for the webhook URL
- **Invalid URL format** or non-HTTPS URL