Webhook Errors¶

This guide helps you diagnose and fix HTTP errors when sending alerts to Parapet Security.

Error Reference¶

400 Bad Request¶

Meaning: The request body couldn't be parsed.

Common Causes:

• Invalid JSON syntax
• Missing required fields
• Encoding issues

Solution:

1. Validate your JSON:

   echo '{"your": "payload"}' | python3 -m json.tool
   

2. Check for common JSON errors:

3. Unescaped quotes in strings
4. Trailing commas

5. Missing brackets

6. Ensure Content-Type header is set:

   Content-Type: application/json
   

401 Unauthorized¶

Meaning: Authentication failed.

Common Causes:

• Missing Authorization header
• Invalid token format
• Token for wrong tenant

Solution:

1. Verify Authorization header format:

   Authorization: Bearer pst_abc123...
   

2. Check for typos in the token

3. Generate a new token:

4. Go to Settings → Service Tokens
5. Click Generate New Token
6. Update your SIEM configuration

403 Forbidden¶

Meaning: Token is valid but not authorized.

Common Causes:

• Token was revoked
• Token expired
• Tenant suspended

Solution:

1. Check token status in Settings → Service Tokens

2. If expired or revoked, generate a new token

3. If tenant suspended, contact support

404 Not Found¶

Meaning: The webhook endpoint doesn't exist.

Common Causes:

• Wrong URL path
• Typo in tenant ID
• Wrong region

Solution:

1. Verify URL format:

   https://webhook-{region}.parapetsecurity.com/webhook/{tenant-id}
   

2. Check your webhook URL in Settings → Service Tokens

3. Ensure region matches your account (us or eu)

413 Payload Too Large¶

Meaning: Alert payload exceeds 1 MB limit.

Common Causes:

• Raw logs included in payload
• Large attachment data
• Base64 encoded binaries

Solution:

1. Reduce payload size:
2. Remove raw log data
3. Summarize large fields

4. Reference external data instead of including it

5. If you need larger payloads, contact support for options

429 Too Many Requests¶

Meaning: Rate limit exceeded.

Common Causes:

• Too many alerts per minute
• Alert flood from SIEM
• Plan limits reached

Solution:

1. Check your rate limits:

1. Implement retry with exponential backoff:

   import time
   
   def send_with_retry(payload, max_retries=5):
       for attempt in range(max_retries):
           response = send_alert(payload)
           if response.status_code != 429:
               return response
   
           wait_time = 2 ** attempt
           time.sleep(wait_time)
   
       raise Exception("Max retries exceeded")
   

2. Filter alerts in your SIEM to reduce volume

3. Consider upgrading your plan

500 Internal Server Error¶

Meaning: Server-side error.

Common Causes:

• Temporary service issue
• Unusual payload format
• Backend processing error

Solution:

1. Retry the request after a few seconds

2. If persistent, check status.parapetsecurity.com

3. Contact support with the request details

502 Bad Gateway¶

Meaning: Load balancer couldn't reach the backend.

Common Causes:

• Service restarting
• Network issues
• High load

Solution:

1. Wait 30 seconds and retry

2. Check status page for outages

3. If persistent, contact support

503 Service Unavailable¶

Meaning: Service temporarily unavailable.

Common Causes:

• Planned maintenance
• Capacity issues
• Service restart

Solution:

1. Check status page for maintenance windows

2. Implement retry logic with backoff

3. Queue alerts locally until service recovers

Debugging Tips¶

Capture Full Request¶

See exactly what your SIEM is sending:

# Start a local listener
nc -l 8080

# Point SIEM at localhost:8080 temporarily
# See the full request

Test with cURL¶

Isolate the issue with a direct test:

curl -v -X POST https://webhook-us.parapetsecurity.com/webhook/{tenant-id} \
  -H "Authorization: Bearer pst_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source": "test", "message": "test"}'

The -v flag shows headers and connection details.

Check Response Body¶

Error responses include details:

{
  "error": {
    "code": "invalid_token",
    "message": "The provided token is not valid",
    "request_id": "abc123"
  }
}

Include the request_id when contacting support.

Retry Best Practices¶

Exponential Backoff¶

wait_times = [1, 2, 4, 8, 16, 32]  # seconds

Retry Conditions¶

Queue for Later¶

If retries fail, queue alerts locally:

import json
from pathlib import Path

QUEUE_DIR = Path("/var/spool/parapet-queue")

def queue_alert(alert):
    queue_file = QUEUE_DIR / f"{alert['id']}.json"
    queue_file.write_text(json.dumps(alert))

def process_queue():
    for queue_file in QUEUE_DIR.glob("*.json"):
        alert = json.loads(queue_file.read_text())
        if send_alert(alert).ok:
            queue_file.unlink()

Getting Help¶

If you can't resolve the error:

1. Note the error code and message
2. Capture the request ID from the response
3. Record the timestamp
4. Contact support@parapetsecurity.com