Developer Documentation

Webhooks Overview

FundraiserMax posts a signed JSON payload to your URL when a contact or list changes. How to add an endpoint, pick events, and check deliveries.

Webhook Overview

Webhooks are the FundraiserMax push channel: when a contact is created, changed, or deleted, or a list's membership changes, we POST a small JSON envelope to a URL you control. They replace the brittle "poll every 5 minutes" pattern most CRM integrations start with, and they're the right choice any time downstream behavior should follow the change rather than a schedule.

Typical use cases: mirroring a new contact into your mailing tool, starting your own welcome message when someone is added to a list, or keeping a data warehouse's contact table current. For anything you'd otherwise build with a cron job that calls the Contacts API on a timer, a webhook is cheaper on rate limits and easier to monitor. Donations, campaigns, and events don't emit webhooks; poll the Donations API for those.

How Webhooks Work

Navigate to Settings > Webhooks in your FundraiserMax dashboard and add a new webhook endpoint URL (must be HTTPS).
Select the event types you want to receive (e.g., contact.created, list.contact.added).
FundraiserMax generates a signing secret for the webhook. Save this secret. You will use it to verify payload signatures.
When a subscribed event occurs, FundraiserMax sends a POST request to your URL with a JSON payload containing the event type and resource data.
Your endpoint should return a 2xx status code within 10 seconds to acknowledge receipt.

Webhook Payload Structure

{
  "id": "whevt_abc123",
  "type": "contact.created",
  "timestamp": "2026-02-16T12:00:00Z",
  "accountId": "acct_123",
  "data": {
    "id": "cnt_def456",
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@example.com",
    "customFields": { "Precinct": "12", "Region": "North County" }
  }
}

Security: Always verify the webhook signature before processing payloads. See the Signature Verification section for details.

When to use webhooks vs. polling vs. MCP

Use webhooks when an external system should react to a contact or list change as it happens: updating an ad audience, mirroring a new donor into a mailing tool, or sending your own welcome message.
Use polling (via the REST API) when you need a periodic reconciliation run or your destination cannot accept inbound HTTP, e.g., nightly imports into a data warehouse or a daily export to a Google Sheet.
Use MCP when an AI assistant needs to read or write FundraiserMax data interactively. MCP is request/response, not push-based; it complements webhooks rather than replacing them.

Operational considerations

Idempotency. The id field on every webhook payload is stable. Store the event IDs you've already processed and short-circuit duplicates. This matters because retries can deliver the same event more than once. See Retry Policy.
Respond fast, work asynchronously. Your endpoint has a 10-second budget. For anything beyond an in-memory log entry, ack the webhook with 200 OKimmediately and process the payload in a background job or queue.
Replay before going live. Use the test endpoint in Settings > Webhooks to replay sample payloads against your staging URL. The signature header is the same format as production, so signature verification can be exercised end-to-end before any real donor data flows.
Monitor failures. Webhook delivery attempts are visible in the dashboard, and FundraiserMax disables an endpoint after five consecutive failed deliveries. Pair this with your own alerting on 2xx-rate so you know before we do.