Webhook Integrations - Outbound

BetterUnite webhooks deliver real-time HTTP notifications to your server whenever key events occur in your account — such as new payments, contact updates, or campaign launches. Use webhooks to integrate BetterUnite data with your own systems or third-party tools without polling the API.

This article outlines the structure of webhook requests, supported event types, and the fields included in each payload.

Overview

When a subscribed event occurs, BetterUnite sends an HTTP POST request to your configured webhook endpoint.

Request Details:

• Method: POST

• Content-Type: application/json

• Body: JSON payload (see examples below)

Each payload contains structured data specific to the event type.

Note: Your endpoint must return an HTTP 2xx status code within 10 seconds to acknowledge receipt. Requests that do not receive a successful response may be retried by BetterUnite.

Supported Webhook Event Types

BetterUnite supports the following webhook event types. You can subscribe to one or more of these events from your account's webhook settings:

• New Contact – Triggered when a new contact is created.

• Update Contact – Triggered when an existing contact is updated.

• New Payment – Triggered when a new payment or donation is recorded.

• Update Payment – Triggered when a payment is updated.

• Campaign Launch – Triggered when a campaign is launched.

• Payment Issue – Triggered when a payment-related issue occurs, such as a failed charge, declined card, or chargeback.

Example Payloads

The examples below show representative payloads for the most common events. Payloads for Update Contact, Update Payment, and Campaign Launch follow the same field structure as their New counterparts above.

1. New Payment Event (NewPayment)

{
  "transactionId": "b1e2c3d4-5678-1234-9abc-def012345678",
  "organization": "BetterUnite Org",
  "intendedAmount": 100.00,
  "grossAmount": 100.00,
  "cardProcessingFees": 2.90,
  "platformFees": 0.00,
  "transactionDateUtc": "2024-02-12T18:30:00Z",
  "tags": "donation,annual",
  "notes": "Thank you for your support!",
  "dedication": "In memory of John Doe",
  "fundName": "General Fund",
  "membershipPlanName": "Annual Supporter",
  "deductibleAmount": 100.00,
  "campaignId": "a1b2c3d4-5678-1234-9abc-def012345678",
  "fundingAccountId": "acct_123456789",
  "paymentType": "CreditCard",
  "referenceNumber": "INV-2024-0001",
  "lineItemsSummary": "General Donation",
  "contactDetails": {
    "organization": "BetterUnite Org",
    "contactId": "c1d2e3f4-5678-1234-9abc-def012345678",
    "firstName": "Jane",
    "lastName": "Smith",
    "companyName": "Acme Corp",
    "emailAddress": "jane.smith@example.com",
    "tags": "donor,newsletter",
    "notes": "",
    "street": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zipcode": "78701",
    "country": "USA",
    "homePhone": "512-555-1234",
    "cellPhone": "512-555-5678",
    "workPhone": "",
    "gender": "Female",
    "contactType": "Individual",
    "contactCustomFields": [
      { "name": "Birthday", "value": "1980-01-01", "misc": "" }
    ]
  },
  "campaignDetails": {
    "campaignId": "a1b2c3d4-5678-1234-9abc-def012345678",
    "organization": "BetterUnite Org",
    "name": "Spring Fundraiser",
    "campaignCreatedOnUtc": "2024-01-01T00:00:00Z",
    "campaignRoute": "spring-fundraiser",
    "status": "Active"
  },
  "transactionCustomFields": [
    { "name": "Source", "value": "Website", "misc": "" }
  ],
  "buUniqueReference": "BU-2024-0001",
  "paymentProcessorUniqueReference": "PP-123456789"
}

2. New Contact Event (NewContact)

{
  "organization": "BetterUnite Org",
  "contactId": "c1d2e3f4-5678-1234-9abc-def012345678",
  "firstName": "Jane",
  "lastName": "Smith",
  "companyName": "Acme Corp",
  "emailAddress": "jane.smith@example.com",
  "tags": "donor,newsletter",
  "notes": "",
  "street": "123 Main St",
  "city": "Austin",
  "state": "TX",
  "zipcode": "78701",
  "country": "USA",
  "homePhone": "512-555-1234",
  "cellPhone": "512-555-5678",
  "workPhone": "",
  "gender": "Female",
  "contactType": "Individual",
  "contactCustomFields": [
    { "name": "Birthday", "value": "1980-01-01", "misc": "" }
  ]
}

Field Reference

Payment Event Fields

Contact Fields

Campaign Fields