Troubleshooting Developer Tools

Running into issues with Driive's developer tools? This guide covers the most common problems and how to fix them.

Webhook deliveries failing

If your webhook deliveries are showing as failed in the delivery log:

Check that your URL is publicly accessible

Your destination URL must be reachable from the public internet. Driive's servers need to make an HTTP POST to your endpoint.
localhost and private network addresses (e.g., 192.168.x.x, 10.x.x.x) won't work. Use a tunneling service like ngrok for local development.

Verify your server returns a 2xx response

Driive considers any non-2xx response (200-299) a failure. Make sure your endpoint returns 200 OK (or another 2xx code) after receiving the payload.
If your server returns a redirect (3xx), Driive does not follow it — this counts as a failure.

Check the delivery log for error details

Open the webhook in Developer > Webhooks and view the delivery history.
Look at the response code column. Common codes:
- 404 — Your endpoint URL is wrong or the route doesn't exist on your server
- 500 — Your server encountered an internal error processing the payload
- 502/503 — Your server is down or unreachable
- Timeout — Your server took too long to respond (return 200 quickly and process asynchronously)

Confirm the webhook is enabled

An easy thing to overlook — check that the webhook's Enabled toggle is on.

Webhook events not firing

If you're not seeing any deliveries at all (not even failed ones):

Check which events are selected — Open the webhook and verify you've subscribed to the event types you expect. For example, if you only subscribed to appointment.created but are waiting for appointment.scheduled, you won't receive it.
Verify the webhook is enabled — A disabled webhook won't fire any events.
Trigger a test event — Use the Send Test button on the webhook detail page to confirm the webhook is active and Driive can reach your endpoint.
Check timing — Webhook deliveries happen in near real-time but are not instantaneous. Wait a few seconds and refresh the delivery log.

Webhook signature verification failing

If your server is rejecting payloads because the HMAC signature doesn't match:

Ensure you're using the correct signing secret

Each webhook has its own signing secret. If you have multiple webhooks, make sure you're using the right secret for the right webhook.
If you recently rotated the secret, update your server to use the new one.

Verify you're hashing the raw request body

The signature is computed over the raw request body string, exactly as sent. If your framework parses the JSON before you compute the hash, you may be hashing a re-serialized version that differs from the original (e.g., different whitespace or key ordering).
Access the raw body directly. In Express.js, use express.raw() or express.text() middleware for the webhook endpoint.

Check for encoding issues

Make sure both the signing secret and the request body are treated as UTF-8 strings.
The signature in the X-Driive-Signature header is a hex-encoded string. Compare hex-to-hex.

Use constant-time comparison

While this won't cause incorrect results, use crypto.timingSafeEqual (Node.js) or hmac.compare_digest (Python) to prevent timing attacks. See Webhook Events and Security for code examples.

API key not working

If your API requests are returning 401 Unauthorized or 403 Forbidden:

Check that the key is active

Navigate to Developer > API Keys and confirm the key is listed and hasn't been revoked.

Check the expiration date

If you set an expiration date when creating the key, it may have expired. Create a new key and update your integration.

Verify permissions match the operation

A Read key cannot create or update data. If you're making a write operation (POST, PUT, PATCH, DELETE), you need a key with Write permissions.

Confirm the Authorization header format

The key must be sent in the Authorization header as a Bearer token:
```
Authorization: Bearer dk_your_api_key_here
```
Check for extra whitespace, missing Bearer prefix, or truncated key values.

Check that you're using the correct organization

API keys are scoped to a specific organization. You cannot use a key from one organization to access another organization's data.

MCP connection refused

If your AI agent can't connect to the Driive MCP server:

Verify the endpoint URL

Copy the endpoint URL directly from Developer > MCP Server. Don't modify it or append additional paths.

Check the API key

The API key must be active and not expired.
The key needs at least Read permissions. For agents that create or update data, you'll need Write permissions.

Test with a simple operation first

Start with a basic read operation (like listing appointment types) to isolate whether the issue is with the connection itself or a specific capability.

Check your AI tool's configuration

Different AI tools have different ways of configuring MCP servers. Double-check the endpoint URL and authentication setup in your tool's configuration. Consult the tool's documentation if needed.

Network connectivity

Ensure your AI tool or server can make outbound HTTPS requests to the Driive MCP endpoint. Firewalls, VPNs, or proxy settings may block the connection.

Rate limiting

Driive API requests (including those made through API keys and the MCP server) are rate-limited to protect system stability.

If you're hitting rate limits:

Implement exponential backoff — When you receive a 429 Too Many Requests response, wait before retrying. Double the wait time with each subsequent retry (e.g., 1s, 2s, 4s, 8s).
Cache responses — If you're repeatedly requesting the same data, cache it locally and only refresh when needed.
Batch operations — Where possible, use batch endpoints instead of making many individual requests.
Spread requests over time — If you're processing a large data export, add a small delay between requests rather than sending them all at once.

Still stuck?

If you've tried the steps above and are still experiencing issues:

Check the Developer Overview to make sure your setup follows the recommended approach
Review the Webhook Events and Security reference for payload and signature details
Reach out to our support team with the specific error message, HTTP response code, and the steps you've already tried — this helps us resolve your issue faster