Troubleshoot Webhook and API Failures

Published · Last updated: May 2026 · 3 min read

Who this is for

Developers whose webhook deliveries are failing or API calls are returning errors, and who need to diagnose and fix the issue.

What you will complete

Diagnose and fix the most common webhook and API failure scenarios.

Diagnosing webhook delivery failures

Step 1: Check the delivery history

Go to Settings → Notification Channels → Delivery History and filter for failed deliveries. The error message tells you what went wrong.

Step 2: Check your endpoint

Verify your webhook endpoint is:

Reachable from the internet (not behind a VPN or private network)
Responding with HTTP 200 within 10 seconds
Using HTTPS (not plain HTTP)

Test with curl from your own machine:

curl -X POST https://your-endpoint.com/webhook \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Step 3: Verify signature validation

If you configured a webhook secret, confirm your signature validation code matches the HMAC-SHA256 pattern exactly. A common mistake is verifying the signature against the parsed JSON instead of the raw request body bytes.

# Correct: use raw bytes
raw_body = request.get_data()  # Flask example

# Wrong: this will fail signature validation
raw_body = json.dumps(request.get_json())  # Do not do this

Common webhook error codes and fixes

Your endpoint returns 401 or 403 Cause: Your endpoint has its own authentication and is rejecting CloudAIPilot's request. Fix: Add the CloudAIPilot IP range or signing secret to your endpoint's allowlist. Or remove auth from the webhook endpoint path and rely on HMAC signature verification instead.

Your endpoint returns 404 Cause: The webhook URL path does not exist on your server. Fix: Verify the full URL in the channel config. Redeploy your webhook handler if necessary.

Your endpoint returns 500 Cause: Your handler is throwing an exception while processing the payload. Fix: Check your server logs. Add try/except around your processing code. Return 200 before processing to prevent retries:

@app.route('/webhook', methods=['POST'])
def webhook():
    # Acknowledge immediately
    payload = request.get_json()
    # Process asynchronously (queue task)
    process_async(payload)
    return {"status": "ok"}, 200  # Always return 200 first

Delivery times out Cause: Your endpoint takes more than 10 seconds to respond. Fix: Move processing to a background task and return 200 immediately.

Common API error codes and fixes

401 Unauthorized Cause: Token missing, expired, or revoked. Fix: Check the Authorization header. Verify the token in Settings → API Tokens. Generate a new token if needed.

403 Forbidden Cause: Valid token but insufficient permissions for this action. Fix: Use a token from a higher-privilege account. Check the role of the account associated with the token.

404 Not Found Cause: The resource ID in the URL does not exist or does not belong to your organization. Fix: Verify the site ID, server ID, or app ID is correct. IDs are organization-specific.

409 Conflict Cause: An operation is already in progress for this resource. Fix: Wait for the current operation to complete (poll the status) then retry.

429 Too Many Requests Cause: You are making too many API calls in a short period. Fix: Implement exponential backoff. Reduce the polling frequency. Cache responses when possible.

500 Internal Server Error Cause: An unexpected error on the CloudAIPilot platform. Fix: Wait 30–60 seconds and retry. If the error persists for more than 5 minutes, email support@cloudaipilot.com.

Testing webhook connectivity

To test your endpoint from outside CloudAIPilot:

# Simulate a CloudAIPilot webhook payload
curl -X POST https://your-endpoint.com/webhook \
  -H "Content-Type: application/json" \
  -H "X-CloudAIPilot-Signature: sha256=test" \
  -d '{"event":"test","timestamp":"2026-05-30T00:00:00Z","data":{}}'

Use this to verify your endpoint is reachable and your handler does not crash on a basic payload.