Troubleshoot Webhooks

Diagnose and fix common webhook delivery problems.

Check webhook logs

View delivery attempts in your Dashboard:

1. Go to Developers > Webhooks
2. Click your endpoint
3. Select Logs tab

Each log entry shows:

• Event type and ID
• Delivery status
• Response code and body
• Timestamp

Common issues

Endpoint returns non-2xx status

Symptoms: Events marked as failed, retries occurring

Causes:

• Application error in webhook handler
• Incorrect URL configured
• Server returning error pages

Solutions:

1. Check your application logs for errors
2. Verify the endpoint URL is correct
3. Test the endpoint manually with curl
4. Ensure handler returns 200 status

Signature verification fails

Symptoms: 400 or 401 responses, signature errors

Causes:

• Wrong signing secret
• Payload modified by middleware
• Clock skew between servers

Solutions:

1. Verify signing secret matches Dashboard
2. Use raw body for signature verification
3. Check server time is synchronized

Pass the raw, unmodified request body bytes to your HMAC-SHA256 computation — do not parse the body as JSON first, then re-serialize it. Any middleware that parses and re-serializes JSON will alter the byte sequence and cause the computed signature to differ from the v1= value in the Plexy-Signature header.

Timeouts

Symptoms: Events show "timeout" status

Causes:

• Handler takes too long (>30 seconds)
• Network issues
• Server overloaded

Solutions:

1. Return 200 immediately, process async
2. Check server resources
3. Review network connectivity

Return HTTP 200 as soon as the request is received, then process the event in a background task or queue. Do not perform database writes, external API calls, or other slow operations before sending the response.

Missing events

Symptoms: Events not arriving, gaps in event history

Causes:

• Endpoint disabled
• Event type not subscribed
• Firewall blocking requests

Solutions:

1. Verify endpoint is enabled
2. Check event subscriptions
3. Whitelist Plexy IPs

Retry behavior

Failed webhooks are retried with exponential backoff:

After 6 failed attempts, the event is marked as failed.

Manually retry events

To retry a failed event:

1. Go to Developers > Webhooks > Logs
2. Find the failed event
3. Click Retry

Test endpoints

Send test events to verify your endpoint:

1. Go to Developers > Webhooks
2. Click your endpoint
3. Click Send Test Event
4. Select event type
5. Click Send

Debug locally

Use webhook forwarding for local development:

# Install Plexy CLI
npm install -g @plexy/cli

# Forward webhooks to localhost
plexy webhooks forward --to localhost:3000/webhooks/plexy

See also

• Configure Webhooks
• Logs - View all API and webhook logs