Test Webhook | Genlogs API Docs

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

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

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