> ## Documentation Index
> Fetch the complete documentation index at: https://storekit.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Troubleshooting

> Diagnose and fix common webhook problems including signature verification failures, incorrect secrets, missing events, and endpoint timeouts in storekit.

Here are common webhook issues and how to resolve them.

## Signature Verification Failing

### Not Using Raw Payload Body

**Problem**: When generating the signature, we use the raw string body of the message payload. If you parse the JSON and then stringify it, the signature won't match.

**Solution**: Always use the raw request body exactly as received:

```javascript theme={null}
// WRONG - parsing and re-stringifying changes the format
const payload = JSON.parse(body);
verify(JSON.stringify(payload), headers); // Will fail!

// CORRECT - use the raw body
verify(rawBody, headers);
```

### Wrong Secret Key

**Problem**: Using the wrong webhook secret or not properly decoding it.

**Solution**:

* Ensure you're using the correct secret for each endpoint (secrets are unique per endpoint)
* Remove the `whsec_` prefix before base64 decoding

### Timestamp Expired

**Problem**: Your server's clock is out of sync, causing valid webhooks to be rejected.

**Solution**: Ensure your server's time is synchronized using NTP.

## Webhooks Not Being Received

### Endpoint Not Accessible

**Problem**: Your endpoint isn't publicly accessible.

**Solution**:

* Ensure your server is running and the endpoint URL is correct
* Check firewall rules allow incoming HTTPS requests
* Verify the endpoint works with a simple curl test

### SSL/TLS Issues

**Problem**: Invalid or expired SSL certificate.

**Solution**: Ensure your endpoint has a valid SSL certificate from a trusted CA.

## Wrong Response Codes

### Returning Errors for Successful Processing

**Problem**: Returning non-2xx status codes even when the webhook was processed successfully.

**Solution**: Always return a 2xx status code when you've successfully received and queued the webhook for processing:

```javascript theme={null}
// CORRECT
app.post('/webhooks', (req, res) => {
  queue.add(req.body); // Add to queue for async processing
  res.status(200).send('OK'); // Acknowledge immediately
});
```

## Timeouts

### Processing Takes Too Long

**Problem**: Your endpoint takes more than 15 seconds to respond.

**Solution**: Process webhooks asynchronously:

```javascript theme={null}
app.post('/webhooks', async (req, res) => {
  // Don't do this - blocks the response
  // await processOrder(req.body);
  
  // Do this instead - queue for background processing
  await queue.add('process-webhook', req.body);
  res.status(200).send('OK');
});
```

## Failure Recovery

### Re-enable Disabled Endpoint

If your endpoint was disabled after consecutive failures:

1. Fix the underlying issue
2. Go to **Settings > Webhooks** in the dashboard
3. Click **Enable Endpoint** on the disabled endpoint

### Replay Failed Messages

To recover missed webhooks after an outage:

1. Go to your endpoint details
2. Click **Options > Recover Failed Messages**
3. Select the time range to replay

<Info>
  Check the webhook logs in your dashboard for detailed error messages and response codes from your endpoint.
</Info>