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

// Use raw body, not parsed JSON
app.post('/webhooks/plexy',
  express.raw({type: 'application/json'}),
  (req, res) => {
    // req.body is Buffer, not parsed object
    const event = plexy.webhooks.constructEvent(
      req.body,
      req.headers['plexy-signature'],
      secret
    );
  }
);

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

app.post('/webhooks/plexy', (req, res) => {
  // Return immediately
  res.status(200).send('OK');

  // Process in background
  setImmediate(() => {
    processEvent(req.body);
  });
});

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