Prompt
How do I debug a broken Zapier connection to my SaaS app?
Latest observation
Here’s a practical way to debug a broken Zapier connection to your SaaS app.
1) Confirm what “broken” means
Common failure modes:
- Auth failure: Zapier can’t authenticate anymore
- Expired/rotated token: OAuth token revoked, refresh token invalid, API key changed
- Webhook failure: Your app can’t deliver events to Zapier
- API change: Your app changed a field, endpoint, or response shape
- Permissions issue: Connected account lost access to required data
- Rate limiting / downtime: Your API is failing intermittently
2) Check Zapier’s side first
In Zapier:
- Open the Zap’s Task History
- Look for the exact error message and status code
- See whether the failure happens during:
- Trigger polling
- Instant trigger/webhook delivery
- Action step
- Connection setup
Useful things to note:
- Error text
- HTTP status code
- Timestamp
- Which account/connection was used
- Whether it fails for one Zap or all Zaps
3) Re-authenticate the connection
If it’s OAuth:
- Disconnect and reconnect the app in Zapier
- Make sure the refresh token flow works
- Verify scopes are still valid
- Check whether your auth server rotated signing keys or changed redirect URLs
If it’s API key/basic auth:
- Confirm the key is still valid
- Check if the user/regenerated key
- Verify headers are being sent correctly
4) Inspect your app’s logs
Look for requests from Zapier around the failure time:
- Auth token exchange
- Trigger polling calls
- Webhook deliveries
- Action requests
Check:
- Status codes
- Response body
- Latency
- Whether the request reached your app at all
If you have request IDs, correlate them with Zapier’s task time.
5) Validate your API responses
Zapier integrations are often sensitive to response shape.
Check that your API returns:
- Valid JSON
- Stable field names
- Consistent types
- Required fields expected by the Zap
- Proper pagination format, if used
Common issues:
- Returning
nullinstead of an array/object - Renaming a field Zapier uses
- Changing nested structure
- Adding a non-JSON error page from a proxy/CDN
6) Test the exact endpoint Zapier uses
Reproduce the failing call with:
- Postman
- curl
- Your own internal debug tool
Use the same:
- Auth headers
- Query params
- Body
- Pagination cursor/limit
- Tenant/account context
If you have a custom Zapier integration, test the trigger/action definition too.
7) Check rate limits and retries
Zapier may retry requests or batch them. Verify:
- Your rate limits aren’t too strict
- Retry responses are appropriate
- You return
429with a sensibleRetry-After - Your app can handle burst traffic from many Zaps
8) Check webhook delivery setup
If you use instant triggers via webhooks:
- Confirm subscription creation succeeds
- Confirm webhook endpoint is reachable from Zapier
- Make sure HTTPS certificate is valid
- Verify firewalls/WAF rules aren’t blocking Zapier
- Ensure event payloads match what Zapier expects
Also confirm you:
- Send the right verification/challenge response, if required
- Keep webhook subscriptions refreshed if your platform requires it
9) Review recent changes
Ask: what changed recently?
- OAuth scopes
- API version
- Response schema
- User permissions
- Domain/redirect URI
- CDN/WAF rules
- Database migration
- Feature flag rollout
A recent deploy is often the culprit.
10) Use Zapier’s integration/debug tools if you build on Zapier Platform
If you maintain a custom app in Zapier Platform:
- Use the CLI/debug logs
- Run
zapier test - Inspect
bundle.authData,bundle.inputData, and raw HTTP responses - Add temporary logging in your
perform/performSubscribe/ auth functions
11) Verify the connection at the account level
Some apps break only for specific tenants:
- User revoked access
- Workspace plan changed
- Required feature disabled
- Data access permission changed
- SSO policy updated
Test with:
- A new user/account
- A newly created Zapier connection
- A different environment if you have staging
12) If nothing is obvious, isolate the layer
Work from outer to inner:
- Zapier task error
- Zapier request logs
- Your API gateway/WAF logs
- Your app logs
- Database/business logic
This usually reveals whether the problem is auth, transport, or payload logic.
Quick checklist
- Check Zapier Task History
- Reconnect the account
- Inspect your API logs
- Test the same request manually
- Confirm response schema hasn’t changed
- Check rate limits
- Review recent deploys
- Verify webhook subscriptions/HTTPS
- Test with a fresh account
If you want, I can also give you:
- a step-by-step debugging runbook, or
- a checklist specific to OAuth vs webhook vs polling triggers.