Integration Troubleshooting

NeedBridge is an email-powered need-matching platform that connects people in need with volunteers through nonprofit organizations. NeedBridge offers integrations including Zapier webhooks, an API, and embeddable widgets. This article covers common integration problems and how to debug them.

Zapier Webhook Not Firing

If you have set up a Zapier integration but your Zap is not triggering when expected, work through these checks:

Check the Webhook URL

  1. In the NeedBridge admin panel, go to your integration or webhook settings.
  2. Verify that the webhook URL matches the one provided by your Zapier trigger.
  3. Make sure the URL was copied completely -- partial URLs will silently fail.
  4. If you recreated the Zap, the webhook URL may have changed. Update it in NeedBridge.

Verify the Zap Is Turned On

Zaps can be paused or turned off. In your Zapier dashboard:

  1. Find the Zap in question.
  2. Check that its status shows "On" (not "Off" or "Paused").
  3. If it was turned off due to errors, review the error log in Zapier before turning it back on.

Test the Webhook

Use Zapier's built-in testing feature:

  1. Open the Zap and go to the trigger step.
  2. Click "Test Trigger" to see if Zapier can receive data from NeedBridge.
  3. If the test receives no data, trigger a test event in NeedBridge (for example, create a test need) and try again.

Check Zapier's Task History

Zapier logs every execution. Check the task history for your Zap to see if it ran but encountered an error in a later step. The problem may not be with the webhook itself but with a subsequent action.

API Key "Unauthorized" Error

If you receive a 401 Unauthorized response when making API calls, the issue is with your API key or how it is being sent.

Check That the Key Is Active

  1. Log in to the NeedBridge admin panel.
  2. Navigate to the API settings section.
  3. Confirm that the API key you are using is listed and has an active status.
  4. If the key was revoked or expired, generate a new one.

Verify the Key Is Copied Correctly

API keys are long strings and it is easy to miss a character when copying:

  1. Copy the key again from the admin panel, making sure to select the entire string.
  2. Check for leading or trailing spaces in your code or configuration.
  3. Make sure you are not accidentally using a placeholder or an old key.

Check the Authorization Header

The API key must be sent in the correct HTTP header. Typically this is the Authorization header:

Authorization: Bearer YOUR_API_KEY

Make sure:

  • The header name is spelled correctly.
  • The word "Bearer" is included with a space before the key.
  • No extra characters or line breaks are present.

Embed Not Displaying

If you have embedded a NeedBridge widget on your website and it is not appearing, check the following:

Verify the Iframe Code

The embed uses an iframe. Make sure:

  1. The embed code is copied exactly as provided in the admin panel.
  2. The src URL in the iframe points to the correct organization and is not truncated.
  3. The iframe has appropriate width and height attributes or CSS styling so it is visible on the page.

Check for CORS Issues

If the embed loads in some browsers but not others, or shows a blank frame, there may be a CORS (Cross-Origin Resource Sharing) issue:

  • Open your browser's developer console (usually F12) and look for CORS-related error messages.
  • Ensure your website's domain is allowed in NeedBridge's embed settings if an allowlist is configured.
  • Some browser extensions (especially ad blockers or privacy tools) can block iframes. Test with extensions disabled.

Check HTTPS

If your website uses HTTPS (which it should), the embed URL must also use HTTPS. Mixed content (an HTTP iframe on an HTTPS page) will be blocked by modern browsers.

Webhook Delivery Failures

If NeedBridge is sending webhooks but the receiving service is not processing them:

Check the Receiving Endpoint

  • Verify that the endpoint URL is correct and the service is running.
  • Make sure the endpoint returns a 200 OK response. NeedBridge may retry on failure, but repeated failures can cause the webhook to be disabled.

Check for Payload Format Issues

  • Review the webhook payload format in the NeedBridge documentation.
  • Make sure your receiving service is parsing the JSON body correctly.
  • Check for content-type header expectations -- NeedBridge sends application/json.

Review Server Logs

Check the logs on your receiving server for incoming requests. If you see the requests arriving but failing to process, the issue is in your handler code, not in NeedBridge.

General Debugging Steps

For any integration issue:

  1. Start with the simplest test. Use a tool like Postman or curl to make a basic API call or trigger a webhook manually.
  2. Check the NeedBridge admin panel for any error messages, logs, or status indicators related to your integration.
  3. Review your code or configuration for typos, stale credentials, or incorrect URLs.
  4. Test in isolation. Rule out network issues, firewalls, or intermediary services by testing the integration from a clean environment.
  5. Contact NeedBridge support if you have verified your configuration and the issue appears to be on the NeedBridge side. Include the endpoint URL, error messages, and timestamps of failed requests.

Related Articles