PWI Webhooks – Donations

Use incoming webhooks to get real-time donation data

Listen for donation events on your PWI Organization so your integration can automatically trigger reactions.

PWI uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like when a donor gives to your Crowdfund project, GroupGive project, or just makes and ad-hoc donation to your nonprofit.

How PWI uses webhooks

A webhook enables PWI to push real-time donation notifications to your app. PWI uses HTTPS to send these notifications to your app as a JSON payload. You can then use these notifications to execute actions in your backend systems.

How to create a webhook endpoint

Creating a webhook endpoint is no different from creating any other page on your website. It’s an HTTP or HTTPS endpoint on your server with a URL. If you’re still developing your endpoint on your local machine, it can be HTTP. After it’s publicly accessible, it must be HTTPS.

How to add your webhook to PWI
  1. Log in to your nonprofit account at projectworldimpact.com/login
  2. From the top menu – select “Operations -> Webhooks”
  3. From the Webhooks dasboard – click: “+ Add endpoint”
  4. Enter your Endpoint URL, Description, version (choose the maximum number you can), and click “Add Endpoint”

 

Handle requests from PWI

Your endpoint must be configured to read and handle donation events. PWI sends events to your webhook endpoint as part of a POST request with a JSON payload.

Step 1 – Check donation object

Each event is structured as an object with related donation attributes nested under donation. Your endpoint must check and parse the payload of each donation.

Here is a sample payload:


        {
          'donation': {
            'contact_id' => '123456',
            'type' => 'person',
            'origin_source' => 'Do id adipisicing ip',
            'origin_unique_key' => 'Est sit consequat',
            'donor_reference' => 'Fugit voluptatem an',
            'title' => 'Mrs',
            'first_name' => 'Sonia',
            'middle_name' => '',
            'last_name' => 'Wharton',
            'company' => 'Freeman Sporting Goods',
            'job_title' => 'Software Eng.',
            'birthday' => '1997-05-17',
            'marital_status' => 'married',
            'gender' => 'male',
            'contact_method' => 'mobile',
            'donor_status' => 'inactive',
            'donor_number' => '624',
            'donation_type' => 'crowdfund',
            'donation_amount' => '75.00',
            'donation_date' => '2022-09-22 00:00:00',
            'donation_status' => 'Success',
            'transaction_reference' => 'ch_3LkvvDLJ6Jy2xNG60YN21HpW',
            'incentive_title' => 'provide 10 t shirts',
            'billing_full_name' => 'Sonia Wharton',
            'billing_first_name' => 'Sonia',
            'billing_last_name' => 'Wharton',
            'billing_email' => 'donor@email.com',
            'billing_address_line1' => '604 Nordic Ct',
            'billing_address_line2' => '',
            'billing_city' => 'Libertyville',
            'billing_state' => 'IL',
            'billing_zip' => '60517',
            'shipping_full_name' => 'Sonia Wharton',
            'shipping_email' => 'donor@email.com',
            'shipping_address_line1' => '604 Nordic Ct',
            'shipping_address_line2' => '',
            'shipping_city' => 'Libertyville',
            'shipping_state' => 'IL',
            'shipping_zip' => '60517',
            'project_id' => '123',
            'project_title' => 'Crowdfund Project 01',
            'project_fund_code' => '123',
          }
        }

 

Step 2 – Return a 200 response

Your endpoint must quickly return a successful status code (200) prior to any complex logic that could cause a timeout.

Step 3 – Execute logic to process donation into your back-end system.

 

Understanding the JSON Payload

Here are the elements in the payload and a brief description for each item:

  • ‘contact_id’
    This is an internally generated identifier for this donor. This will be a unique value for every donor, but does not corollate to any values in your system.
  • ‘type’
    This is the ‘type’ of donor – ie, a ‘person’, ‘organization’, etc.
  • ‘origin_source’
    This is a field in our CRM that we allow you to populate to identify where the contact came from. This can either be populated during the contact import process, or manually via the Charity CRM tool. If the donor was NOT imported from your system, this will be blank.
  • ‘origin_unique_key’
    This data is a field in our CRM that we allow you to populate with a unique identifier, so that you can tie the data back to your origin system without any matching complexities. This is typically a primary key value/id for a donor in your system. If the donor was NOT imported from your system, this will be blank.
  • ‘donor_reference’ 
    This is a field in our CRM that allows you to populate/update with any specific reference number/value for the donor. This is included in this payload so that you can easily match the data with your back-end system without any matching complexities.
  • ‘title’
    Donor’s title – ie, Mr, Mrs, etc.
  • ‘first_name’ 
    Donor’s first name
  • ‘middle_name’
    Donor’s middle name
  • ‘last_name’ 
    Donor’s last name
  • ‘company’
    Donor’s company name.
  • ‘job_title’
    Donor’s job title
  • ‘birthday’ 
    Donor’s birth day.
  • ‘marital_status’ 
    Donor’s martial status
  • ‘gender’
    Donor’s gender
  • ‘contact_method’ 
    Donor’s preferred method of contact (ie, mobile, email, etc)
  • ‘donor_status’ 
    This is a field that you’re able to set in our CRM to determine the donor’s status (ie, active donor, etc).
  • ‘donor_number’
    This is a unique number that you have allocated to the donor through the contact import process, or manually added via the Charity CRM interface. If you have not allocated a value, this will be empty.
  • ‘donation_type’
    This is the source of the donation in the context of PWI Products. For example, the values could be: “crowdfund” (Crowdfund project donation), “groupgive” (GroupGive project donation), “donation” (ad-hoc donation to your nonprofit via your profile or Text2Give links).
  • ‘donation_amount’
    The donation amount – formatted with 2 decimal places.
  • ‘donation_date’ 
    The date of the donation – formatted “YYYY-MM-DD”
  • ‘donation_status’ 
    The response from the payment gateway for the donation – this will always be “Success”
  • ‘transaction_reference’
    The transaction reference number returned from your payment gateway
  • ‘incentive_title’ 
    If the donation is to a Crowdfund project – the incentive_title will be the name of the particular donation incentive selected.
  • ‘billing_full_name’
    ‘billing_first_name’
    ‘billing_last_name’
    ‘billing_email’ 
    ‘billing_address_line1’
    ‘billing_address_line2’ 
    ‘billing_city’ 
    ‘billing_state’
    ‘billing_zip’
    The above are all the default billing information.
  • ‘shipping_full_name’
    ‘shipping_email’ 
    ‘shipping_address_line1’
    ‘shipping_address_line2’
    ‘shipping_city’
    ‘shipping_state’ 
    ‘shipping_zip’
    The above are all the default shipping information (typically only provided for Crowdfund Incentive donations).
  • ‘project_id’ 
    If the donation was to a Crowdfund Project or a GroupGive Project – this will be the unique identifier of that particular project.
  • ‘project_title’ 
    If the donation was to a Crowdfund Project or a GroupGive Project – this will be the title of that particular project.
  • project_fund_code’
    If the donation was to a Crowdfund Project or a GroupGive Project – this will be the fund code that has been added to that particular project.
Back To Top