Integrations

Integrations

NeedBridge is an email-powered need-matching platform for nonprofits -- foster care agencies, churches, disaster relief organizations, and community groups. While NeedBridge works as a standalone platform, integrations let you connect it with the other tools your organization uses -- CRMs, spreadsheets, communication platforms, and your own website. This guide covers API keys, Zapier, webhooks, embed codes, and security best practices.

API Keys

API keys allow external tools and custom integrations to interact with NeedBridge programmatically. They authenticate requests to the NeedBridge API.

Creating an API Key

  1. Go to Settings in the admin panel.
  2. Find the Integrations or API Keys section.
  3. Click to create a new API key.
  4. Give the key a descriptive name that identifies what it will be used for.
  5. Copy the key immediately -- it will not be shown again after you close the dialog.

Naming Best Practices

Create one API key per integration or use case. This makes it easy to revoke access for a specific integration without affecting others.

Good names:

  • "Zapier - Volunteer Sync"
  • "Google Sheets - Weekly Report"
  • "Website Embed - Main Site"
  • "CRM Integration - Salesforce"

Avoid:

  • "API Key 1" (not descriptive)
  • "Main Key" (too broad -- use separate keys per integration)
  • Using one key for everything (if it is compromised, all integrations are affected)

Revoking an API Key

If an API key is no longer needed or may have been compromised:

  1. Go to Settings and find the API Keys section.
  2. Locate the key you want to revoke.
  3. Click to revoke or delete it.
  4. Confirm the action.

Revoking a key immediately stops all integrations using that key. Any external tool configured with the revoked key will stop working until it is updated with a new key.

Security for API Keys

  • Treat API keys like passwords. Do not share them in emails, chat messages, or public repositories.
  • Store keys in a password manager or secure secrets vault.
  • Revoke keys you are no longer using. Do not leave old keys active "just in case."
  • Use one key per integration so you can revoke access granularly.
  • Rotate keys periodically if your organization's security policies require it.
  • Never commit API keys to version control (Git, GitHub, etc.).

Zapier Integration

Zapier is a no-code automation platform that connects NeedBridge to hundreds of other apps. With Zapier, you can automatically sync data between NeedBridge and tools like Google Sheets, Slack, Salesforce, Mailchimp, and more.

Setting Up Zapier

  1. Enable the Zapier integration in NeedBridge. Go to Settings in the admin panel and find the Zapier integration section. Enable it.
  2. Get your webhook URL. NeedBridge provides a webhook URL that Zapier will use to receive data. Copy this URL.
  3. Create a Zap in Zapier. Log in to your Zapier account and create a new Zap (automation).
  4. Configure the trigger. Select NeedBridge as the trigger app (or use the "Webhooks by Zapier" trigger with your webhook URL). Choose the event that should start the automation.
  5. Configure the action. Select the destination app (Google Sheets, Slack, etc.) and configure what should happen when the trigger fires.
  6. Test the Zap. Run a test to make sure data flows correctly from NeedBridge to your destination.
  7. Turn the Zap on. Once tested, activate the Zap so it runs automatically.

Zapier Triggers

NeedBridge can trigger automations when the following events occur:

  • New need posted -- Fires when a case worker publishes a new need. Useful for syncing needs to a spreadsheet, sending a Slack notification, or updating a dashboard.
  • New volunteer -- Fires when a new volunteer signs up. Useful for adding volunteers to a CRM, email marketing list, or Google Sheet.
  • New case worker -- Fires when a new case worker registers. Useful for notifications to admins or HR systems.
  • Need claimed -- Fires when a volunteer claims a need. Useful for Slack alerts or CRM updates.
  • Need completed -- Fires when a need is marked as completed. Useful for impact tracking in external systems.

Common Zapier Recipes

Here are some popular automation patterns:

Add New Volunteers to Google Sheets

  • Trigger: New volunteer in NeedBridge
  • Action: Create a new row in Google Sheets
  • Use case: Maintain a backup volunteer list in a spreadsheet that non-NeedBridge team members can access

Slack Notification on New Claims

  • Trigger: Need claimed in NeedBridge
  • Action: Send a message to a Slack channel
  • Use case: Alert your team in real time when a volunteer steps up so case workers can follow up quickly

CRM Sync for New Volunteers

  • Trigger: New volunteer in NeedBridge
  • Action: Create a contact in Salesforce (or HubSpot, or another CRM)
  • Use case: Keep your donor/volunteer CRM in sync with NeedBridge signups

Email Marketing Sync

  • Trigger: New volunteer in NeedBridge
  • Action: Add subscriber to Mailchimp list
  • Use case: Include NeedBridge volunteers in your organization's general newsletter

Weekly Impact Summary

  • Trigger: Schedule (weekly)
  • Action: Pull NeedBridge data via API and send a formatted email or Slack message
  • Use case: Automated weekly summary for leadership

Zapier Default Volunteer Frequency

Volunteers added to NeedBridge through Zapier default to Weekly notification frequency. This is different from CSV imports, which default to Daily. The weekly default for Zapier-added volunteers reduces email volume for contacts who may have been synced from external systems and may not expect frequent notifications. Admins can change the frequency after import.

Troubleshooting Zapier

  • Zap is not firing: Check that the Zap is turned on in Zapier. Verify that the webhook URL in NeedBridge matches the one in Zapier. Try creating a test event in NeedBridge (post a need, add a volunteer) and check Zapier's task history.
  • Data is missing fields: Check the field mapping in your Zap. Make sure each NeedBridge field is mapped to the correct destination field.
  • Duplicate records: If your Zap creates duplicates in the destination app, add a lookup step to check for existing records before creating new ones.
  • Zapier errors: Check the error message in Zapier's task history. Common issues include expired API keys, invalid field values, or rate limits on the destination app.

Webhook Configuration

For organizations with development resources, NeedBridge supports direct webhook configuration as an alternative to Zapier.

How Webhooks Work

A webhook is a URL that NeedBridge sends data to whenever a specific event occurs. When a trigger event happens (a new need, a new volunteer, a claim, etc.), NeedBridge makes an HTTP POST request to your webhook URL with the event data in JSON format.

Setting Up Webhooks

  1. Go to Settings and find the webhook configuration section.
  2. Enter the URL where you want to receive webhook data.
  3. Select which events should trigger the webhook.
  4. Save the configuration.
  5. Test by triggering an event and checking that your endpoint receives the data.

Webhook vs. Zapier

  • Use Zapier if you want no-code automation and are connecting to popular apps like Google Sheets, Slack, or Salesforce.
  • Use webhooks if you have a developer who can build custom integrations, if you need to connect to systems Zapier does not support, or if you want full control over how data is processed.

Embed Code

NeedBridge provides embed code that lets you place NeedBridge components -- the volunteer signup form and the needs browser -- directly on your own website. This way, visitors can interact with NeedBridge without leaving your site.

What You Can Embed

  • Volunteer signup form -- A form where visitors can sign up as volunteers, choosing their areas and notification preferences. Everything they would see on your NeedBridge volunteer signup page, embedded on your website.
  • Needs browser -- A list of current open needs that visitors can browse and click through to claim. This is useful for showing your community what help is needed right now.

Where to Find the Embed Code

The embed code is available in the Settings or Integrations section of the admin panel. You will find code snippets for both the volunteer signup form and the needs browser.

Embedding Methods

Method 1: JavaScript Embed (Recommended)

Add the NeedBridge embed script to your page, then use JavaScript to render the component:

<script src="https://[your-domain]/embed.js"></script> <div id="needbridge-volunteer-signup"></div> <script> NeedBridge.embedVolunteerSignup({ container: '#needbridge-volunteer-signup', org: 'your-org-slug', height: '800px' }); </script>

For the needs browser:

<div id="needbridge-needs-browser"></div> <script> NeedBridge.embedNeedsBrowser({ container: '#needbridge-needs-browser', org: 'your-org-slug', max: 6, filters: false, height: '600px' }); </script>

Method 2: Direct Iframe

You can also use a simple iframe tag:

<iframe src="https://[your-domain]/embed/volunteer-signup?org=your-org-slug" width="100%" height="800" frameborder="0"> </iframe>

Customization Options

For the needs browser embed:

  • max -- Maximum number of needs to display (default: 6)
  • filters -- Whether to show filter controls (default: false)
  • height -- Height of the embedded component
  • autoResize -- Whether the iframe automatically resizes based on content (default: true)

Platform-Specific Instructions

Embed code works on most website platforms:

  • WordPress -- Add the embed code to a page or post using a Custom HTML block
  • Squarespace -- Add the embed code to a Code Block
  • Wix -- Use the HTML Embed widget
  • Other platforms -- Any platform that supports custom HTML can use the embed code

Tips for Embedding

  • Replace your-org-slug with your actual organization slug from Settings
  • Replace [your-domain] with your NeedBridge instance domain
  • Test the embed on your website after adding it to make sure it loads correctly
  • If the embed does not display, check that your website platform allows external scripts and iframes
  • Use the JavaScript embed method for better auto-resizing behavior

Volunteer Data Sync to External Tools

Organizations often need to keep volunteer data synchronized between NeedBridge and other tools like CRMs, email marketing platforms, or donor management systems.

Sync Options

  1. Zapier automations -- Set up a Zap to automatically sync new volunteers to your external tool when they sign up.
  2. CSV export and import -- Periodically export your volunteer list from NeedBridge (Settings > Data Export) and import it into your external tool.
  3. API integration -- Use the NeedBridge API with your API key to programmatically pull volunteer data and push it to other systems.
  4. Webhooks -- Configure webhooks to receive real-time volunteer data when signups occur.

What Data Can Be Synced

  • Volunteer name, email, and phone number
  • Area subscriptions
  • Notification frequency
  • Signup date
  • Claim history and engagement data

Tips for Data Sync

  • Decide on a sync direction: one-way (NeedBridge to external tool) or two-way. Two-way sync is more complex and may require custom development.
  • Use email address as the unique identifier when matching records across systems.
  • Test your sync with a small batch before running it on your full volunteer list.
  • Monitor for duplicates and set up deduplication rules in your destination system.

Security Best Practices

Integrations involve sharing data between systems. Follow these practices to keep your organization's data safe:

  • Store API keys in a password manager or secure vault, not in plain text files, emails, or shared documents.
  • Revoke unused API keys immediately. When an integration is decommissioned or a team member who managed an integration leaves, revoke the associated key.
  • Use HTTPS endpoints for all webhook URLs. Never send data to unencrypted HTTP endpoints.
  • Limit API key permissions to what each integration actually needs, if permission scoping is available.
  • Monitor integration activity. Periodically review which integrations are active and what data they are accessing.
  • Do not share API keys between integrations. Create a separate key for each tool or connection.
  • Review Zapier task history regularly to ensure data is flowing correctly and no sensitive information is being sent to unintended destinations.

Troubleshooting Integrations

Embed Not Loading

  • Verify the organization slug is correct
  • Check that the embed URL is accessible (visit it directly in a browser)
  • Look for browser console errors that might indicate JavaScript or CORS issues
  • Make sure your website platform allows external scripts and iframes

Zapier Not Triggering

  • Confirm the Zap is turned on
  • Check that the webhook URL in NeedBridge Settings matches the one in Zapier
  • Create a test event and check Zapier's task history for activity
  • Verify your NeedBridge API key has not been revoked

API Requests Failing

  • Check that your API key is valid and has not been revoked
  • Verify you are using the correct API endpoint URL
  • Check the response body for error messages that explain what went wrong
  • Ensure your request format matches the API documentation

Webhook Not Receiving Data

  • Confirm the webhook URL is correct and accessible from the internet
  • Check that your server is returning a 200 OK response to NeedBridge webhook requests
  • Look at your server logs for incoming requests
  • Verify the webhook is enabled and the correct events are selected in NeedBridge Settings