Skip to content
English
More support
Back to main site
  • There are no suggestions because the search field is empty.

Webhook and Metadata Tracking for Your Organization

HopeGives allows organizations to receive real-time donation data through webhooks and track internal data points using custom metadata fields. This guide walks you through both features so your systems can stay in sync with activity on the platform.

Part 1: Webhook Setup

A webhook is a secure URL that allows your system to automatically receive donation events from HopeGives. When someone donates or receives a refund, we’ll instantly send a POST request to your webhook with all relevant details.

How to Configure Your Webhook

  1. Go to your Settings tab in the organization dashboard.

  2. In the Subscription section, enter your Webhook URL (must be HTTPS).

  3. Select the events you'd like to receive:

    • Donation Succeeded

    • Donation Refunded

  4. Click Save to enable the webhook
Screenshot 2025-05-28 at 9.40.51 AM

 

Tip: You can disable or update the webhook at any time by returning to this section.

 

Part 2: Custom Metadata Fields

HopeGives supports up to 6 custom metadata fields that allow you to collect and track specific information about missionaries when they onboard with your organization. These fields are included in webhook payloads, making it easy to match donations to your internal records.

How to Configure Metadata Fields

  1. In the Organization Metadata section, click to expand any of the six available slots.

  2. Customize each field:

    • Label: Displayed to the missionary (Example, "Missionary Account ID")

    • Payload Name: Key used in webhook data (e.g., metadata1)

    • Tooltip (Optional): Help text to guide users (e.g., "This is the ID you are issued when commissioned")

    • Help Link (Optional): Link to additional guidance or documents

  3. Toggle Is Enabled to activate the field.

  4. Click Save to confirm.

Screenshot 2025-05-28 at 9.44.42 AM

    Enabled fields will be shown during missionary onboarding and their values will be tied to all campaign activity for that missionary.

    PayLoad Example

    {
      "eventType": "donation.succeeded",
      "transaction": {
        "transactionId": "txn_abc123456",
        "transactionPaypalId": "PAYPAL987654321",
        "transactionAmount": 236,
        "transactionTipAmount": 36,
        "transactionFeeAmount": 7.55,
        "transactionPlatformFeeAmount": 14,
        "transactionDonationAmount": 178.45,
        "billingFirstName": "Jane",
        "billingLastName": "Doe",
        "billingAddress1": "123 Sample Street",
        "billingAddress2": "Unit 5",
        "billingCity": "Exampleville",
        "billingState": "CA",
        "billingZip": "90210",
        "billingCountry": "US",
        "billingPhone": "5551234567",
        "billingEmail": "jane.doe@example.com",
        "transactionDate": "2025-07-10T02:00:38.013Z"
      },
      "campaignMetadata": {
        "campaignId": "camp_456xyz789",
        "campaignName": "Clean Water for All",
        "userId": "user_001abc999",
        "userFirstName": "Alex",
        "userLastName": "Smith",
        "userEmail": "alex.smith@example.com",
        "projectId": "101",

        "recurringDonatonId"; abcded12345

        "metadata1": "custom_value",
        "metadata2": "custom_value"
        "metadata3": "custom_value"
      },
      "querystring": ""
    }

    Field Reference

    Top-level

    Key Description
    event_type The type of webhook event (donation.succeeded)
    transaction Object containing transaction-specific data
    campaign_metadata Object containing campaign-related metadata
    querystring Captures any query parameters passed (usually empty)
     

    transaction Object

    Key Description
    transaction_id Unique ID for the donation on our system
    paypal_transaction_id PayPal’s reference ID for this transaction
    total_amount Total amount charged to the donor (Including any T.I.P. given to HopeGives 
    tip_amount Optional tip added to support HopeGives
    fee_amount Processing fees (e.g. PayPal)
    platform_fee_amount Platform fee retained by HopeGives
    donation_amount Net amount is Total amount less T.I.P and fees.
    date ISO 8601 timestamp of the donation
     

    billing Object (inside transaction)

    Key Description
    first_name Donor’s first name
    last_name Donor’s last name
    address_1 Billing address line 1
    address_2 Billing address line 2
    city Billing city
    state Billing state
    zip Billing postal code
    country Billing country code (US)
    phone Donor’s phone number
    email Donor’s email address
     

    campaign_metadata Object

    Key Description
    campaign_id Unique ID for the campaign
    campaign_name Name of the campaign
    user_id ID of the campaign creator
    user_first_name First name of the campaign creator
    user_last_name Last name of the campaign creator
    user_email Email of the campaign creator
    project_id Internal project tracking ID found on each campaign
    recurring_Donation_id   Only Present if the donor has set recurring donation
    metadata_1 Optional metadata (use case may vary)
    metadata_2 Optional metadata (use case may vary)

    Best Practices

    • Use HTTPS for your webhook URL.

    • Validate incoming requests with a token or signature (coming soon).

    • Clearly label metadata fields to reduce onboarding errors.

    • Only enable fields you plan to use.

    • Test your webhook endpoint with sample data before going live.

    Need help getting your webhook endpoint set up or planning your metadata structure? Contact Support