Webhook Debugging

When webhook deliveries fail, use the Webhook Logs in your Skribby dashboard to diagnose issues. This guide covers common problems and how to resolve them.

Accessing Webhook Logs

Navigate to Webhook Logs in the Skribby Dashboard to view delivery attempts.

Each log entry shows:

• Timestamp: When the webhook was sent
• URL: Your webhook endpoint
• Status Code: HTTP response from your server
• Request Body: The event payload
• Response Body: Your server's response (first 250 characters)

Webhook Delivery Lifecycle

1. Bot Event: A status change or other event occurs
2. Webhook Queued: Skribby queues the webhook for delivery
3. HTTP POST: Request is made to your webhook_url
4. Your Server: Should respond with 2xx status
5. Response Logged: Result is logged regardless of success/failure

⚠️ No Automatic Retry: Currently, failed webhooks are not automatically retried. A single delivery attempt is made for each event.

Response Codes

Any 2xx response is considered successful delivery. Non-2xx responses are logged as failed deliveries.

If the log shows a 500 status with "Request Failed" in the response body, the HTTP request itself failed (DNS failure, connection refused, SSL error, or timeout).

Signature Verification

Skribby signs all webhooks so you can verify authenticity. See Webhook Security for full details.

Verification Checklist

1. Get your webhook secret: Found in Webhook Settings
2. Read the signature headers:
   • X-Skribby-Signature: HMAC-SHA256 signature
   • X-Skribby-Timestamp: Unix timestamp
3. Compute expected signature: HMAC-SHA256(timestamp + "." + rawBody, secret)
4. Compare signatures: Use constant-time comparison
5. Check timestamp: Reject if too old (prevent replay attacks)

Common Signature Issues

Example Verification (Node.js)

Copyconst crypto = require('crypto');

function verifyWebhook(req, secret) {
    const signature = req.headers['x-skribby-signature'];
    const timestamp = req.headers['x-skribby-timestamp'];
    const rawBody = req.rawBody; // Must be raw, not parsed

    if (!signature || !timestamp || !rawBody) {
        return false;
    }

    const expected = crypto
        .createHmac('sha256', secret)
        .update(`${timestamp}.${rawBody}`)
        .digest('hex');

    if (signature.length !== expected.length) {
        return false;
    }

    return crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expected),
    );
}

Delivery Best Practices

Respond Quickly

• Return 200 OK immediately
• Process the event asynchronously
• Don't do heavy work in the handler

Copy// Good: Quick response, async processing
app.post('/webhook', (req, res) => {
    res.status(200).send('OK');
    processEventAsync(req.body); // Queue for later
});

// Bad: Slow response
app.post('/webhook', async (req, res) => {
    await heavyProcessing(req.body); // Blocks response
    res.status(200).send('OK');
});

Error Handling

Return appropriate status codes:

• 200: Event received and will be processed
• 400: Malformed payload (helps us identify issues)
• 500: Your handler crashed (check your logs)

Troubleshooting Specific Issues

"No webhooks received"

1. Verify webhook_url is set on the bot
2. Check URL is publicly accessible (not localhost)
3. Confirm HTTPS is working (valid certificate)
4. Check firewall allows inbound connections
5. Look for the request in your server logs

"Webhooks delayed"

Webhooks are queued and sent asynchronously. Typical delivery time is under 5 seconds. If delays persist:

• Check Skribby status page for system issues
• Verify your server isn't slow to respond

"Webhook URL keeps changing"

The webhook_url is set per-bot. If you need to change it:

• Update the bot via PATCH /bot/{id}
• Or set the correct URL when creating new bots

Managing Webhook Settings

Regenerating Your Secret

Navigate to Webhook Settings to regenerate your secret.

⚠️ Breaking Change: Regenerating invalidates the old secret immediately. Update your verification code before regenerating.

Testing Webhooks

1. Use a service like webhook.site to inspect payloads
2. Set it as your webhook_url temporarily
3. Create a test bot to trigger events
4. Verify the payload structure and headers