Webhook Documentation

General Namespaces

  • AD_ Activity Details
  • PD_ Personal Details
  • DD_ Donation Details
  • RD_ Registration Details
  • CF_ Custom Field Details
  • RS_ Recurring Setup
  • IOS_ Item Order Status
  • SPD_ Sponsorship Details
  • VD_ Volunteer Details

All webhooks are added to a queue and sent at set intervals.


new_activity 

  • Data related to new activities. Can be triggered by supporters on campaign pages, mobile apps, and by the organization on the Manual Payments section. Examples of activities include Mailing List sign-ups, Donations, Registrations, Volunteer, etc.
  • Each activity creates a new webhook record, so one transaction can result in multiple new_activity webhooks.

Note: Transaction-related (order level) details will be posted in the new_transaction webhook.


Activity Types:

  • Mailing List
  • Donation
  • E Registration
  • G Store Order (G is a legacy code from the days when it was called Gift or Karma Gift)
  • V Volunteer
  • R Sponsorship
  • RD Refund
  • RS Recurring Setup (Recurring Donations create this activity type)

Example activity webhooks:


Donation Activity

    {

        "webhook_record_id": "1145",

        "webhook_trigger_type": "new_activity",

        "master_activity_auto_id": "176957",

        "activity_type": "Donation",

        "activity_order_format": "D1098854_A",

        "transaction_id": "137405",

        "AD_payment_id": "D1098854_A",

        "AD_master_activity_auto_id": "176957",

        "AD_transaction_id": "T1137405",

        "AD_contact_id": "Todd Test (CID638-1000015)",

        "AD_transaction_date": "2021-04-01",

        "AD_transaction_time": "02:04 ",

        "AD_transaction_day": "Thursday",

        "AD_campaign_title": "Multi Tool Campaign",

        "AD_campaign_id": "4809",

        "PD_individual_or_bussiness": "Individual",

        "PD_first_name": "Todd",

        "PD_last_name": "Test",

        "PD_email": "[email protected]",

        "PD_address": "123 Street",

        "PD_address2": "",

        "PD_city": "Nashville",

        "PD_state": "TN",

        "PD_postal_code": "3720",

        "PD_country": "US",

        "PD_phone_number_type": "Mobile",

        "PD_phone_country_code": "+1",

        "PD_phone ": "6159621144",

        "PD_wants_to_remain_anonymous": "No",\

        "DD_payment_title": "Bronze",

        "DD_payment_method": "Credit Card",

        "DD_payment_description": "Thanks for making an impact!",

        "DD_donation_price": "25.00",

        "DD_donation_order_amount": "136.11",

        "DD_frequency": "onetime",

    },


Registration Activity

    {

        "AD_associated_transaction_id": "T1137405",

        "AD_campaign_id": "4809",

        "AD_campaign_title": "Multi Tool Campaign",

        "AD_contact_id": "Todd Test (CID638-1000018)",

        "AD_day_of_week": "Thursday",

        "AD_registration_order_id": "E1012690_A",

        "AD_transaction_date": "2021-04-01",

        "AD_transaction_time": "02:04 ",

        "PD_individual_or_bussiness": "Individual",

        "PD_participant_email": "[email protected]",

        "PD_participant_first_name": "Todd",

        "PD_participant_last_name": "Test",

        "PD_wants_to_remain_anonymous": "No",

        "RD_amount_paid": "50.00",

        "RD_fair_market_value": "50.00",

        "RD_registrant_email": "[email protected]",

        "RD_registrant_first_name": "Todd",

        "RD_registrant_last_name": "Test",

        "RD_registration_confirmation_pdf_url": "https://www.ourorganization.info/assets/uploads/pdf/registration_confirmation_test_04012021_176959_21617300267.pdf"",

        "RD_registration_group_name_id": "Test Event Again (4668)",

        "RD_registration_price": "50.00",

        "RD_registration_type": "General Admission",

        "RD_sales_tax_amount": null,

        "RD_shipping_cost": null,

        "RSD_registration_completion_date": "2021-04-01",

        "RSD_registration_completion_status": "Completed",

        "activity_order_format": "E1012690_A",

        "activity_type": "Registration",

        "master_activity_auto_id": "176958",

        "transaction_id": "137405",

        "webhook_record_id": "1146",

        "webhook_trigger_type": "new_activity"

    }


Online Store Activity

    {

        "AD_associated_transaction_id": null,

        "AD_campaign_id": null,

        "AD_campaign_title": "",

        "AD_day_of_week": "Wednesday",

        "AD_item_order_id": null,

        "AD_transaction_date": "1969-12-31",

        "AD_transaction_id": "T1000000",

        "AD_transaction_time": "07:00 ",

        "IOS_item_order_completion_date": null,

        "IOS_item_order_status": null,

        "PD_email": null,

        "PD_first_name": null,

        "PD_individual_or_bussiness": "Business",

        "PD_last_name": null,

        "PD_postal_code": null,

        "PD_wants_to_remain_anonymous": null,

        "SD_amount_paid": "$0.00",

        "SD_fair_market_value": null,

        "SD_item_price": null,

        "SD_item_type": " ()",

        "SD_online_store_id": " ()",

        "SD_shipping_cost": null,

        "SD_tax_deductible_amount": null,

        "activity_order_format": "G1004094_A",

        "activity_type": "Online Shop",

        "master_activity_auto_id": "176960",

        "transaction_id": "137405",

        "webhook_record_id": "1148",

        "webhook_trigger_type": "new_activity"

    }


Refund Activity

 {

        "webhook_record_id": "1145",

        "webhook_trigger_type": "new_activity",

        "master_activity_auto_id": "176957", 

        "activity_type": "Refund",

        "activity_order_format": "RD1098854",

        "transaction_id": "137405",

        "AD_refund_dispute_id": "D1098854_A",

        "AD_transaction_id": "T1137405",

        "AD_associated_transaction_id": "T1137405"

        "AD_transaction_date": "2021-04-01",

        "AD_transaction_time": "02:04 ",

        "AD_day_of_week": "Thursday",

        "AD_campaign_title": "Multi Tool Campaign",

        "AD_campaign_id": "4809",

        "PD_individual_or_bussiness": "Individual",

        "PD_first_name": "Todd",

        "PD_last_name": "Test",

        "PD_email": "[email protected]",

        "RD_refund_amount": "-25.00",

        "PD_payment_method": "Credit Card",

    },


new_contact / update_contact / delete_contact

  • When a new contact is created through a manual entry in the Customer Dashboard Contacts Manager or through a new transaction, a new_contact webhook is sent.
  • When an existing contact is edited manually in the Customer Dashboard Contacts Manager, an existing contact’s information is changed during a transaction, or a contact’s details are changed via an updated transaction in the admin panel, an update_contact webhook is sent
    • If an existing Primary field is edited, the new Primary value will be included in an ADDED_ key, and the old Primary value included in an OLD_ key
    • When a new field is created and set as Primary in the Customer Dashboard Contacts Manager, the new Primary values will be included in the request as well as an add_primary: “Yes” key:value pair.
  • When an existing contact is deleted in the Customer Dashboard Contacts Manager, a delete_contact webhook is sent.
  • When a tag is added to a contact or contact tag in the CRM, an update_contact webhook is sent.


Example new_contact/update_contact/delete_contact Webhooks

[

    {

        "webhook_record_id": "1822",

        "webhook_trigger_type": "update_contact" || “new_contact” || “delete_contact”

        "user_id": "638",

        "contact_id": "CID638-1000039",

        "ADDED_CF": "false",

        "business_name": "My Biz",

        "title": "NA",

        "first_name": "todd",

        "last_name": "",

        "address_line": "123 Street",

        "address_line2": "NA",

        "city": "Nashville",

        "contact_id": "CID638-1000039",

        "contact_type": "Individual",

        "country_code": "US",

        "crm_first_name": "",

        "email": "[email protected]",

        "first_crm_id": "",

        "first_inserted_date": "",

        "first_primary": "",

        "phone_country_code": "+1",

        "phone_no_type": "Mobile",

        "phone_number": "1234567890",

        "postal_code": "12345",

        "record_type": "update",

        "state": "TN",

        "suffix": "NA",

        "updated_on": "2021-06-30 10:27:22",

    }

]


new_transaction

  • Transactions created on campaign landing pages, manual campaign transactions in the Customer Dashboard, and widgets will send a new_transaction webhook.
  • Refunding a Transaction will trigger a new_transaction webhook. Webhooks will be sent for both the refund of the base transaction as well as the processing fee.
  • Transaction_type rows in transaction webhooks will map to types in the Activity Types list.

 


new_transaction example

The example webhook below is for a Volunteer transaction:
[
    {
        "address": "123 Street ",
        "associated_activity_IDs": "V1005666_A,M1020782_A",
        "business_organization_name": "",
        "campaign_name": "Multi Tool Campaign",
        "cause_id": "4809",
        "city": "Nashville",
        "contact_id": "CID638-1000040",
        "country": "US",
        "country_code": "+1",
        "custom_field_status": "false",
        "email": "[email protected]",
        "fee_by_supporter": "N",
        "first_name": "Todd",
        "id": "9006",
        "individual_or_business": "Individual",
        "last_name": "",
        "net_received": "0.00",
        "payment_method": "",
        "phone_no_type": "M",
        "phone_number": "",
        "postal_code": "12345",
        "posted_amount": "0.00",
        "processing_fee": "0.00",
        "settlement_date": "2021-06-30 17:00:52",
        "state": "TN",
        "support_message": "",
        "total_charged_amount": "0.00",
        "total_transaction_amount": "0.00",
        "transaction_date": "2021-06-30 17:00:52",
        "transaction_id": "T1143281",
        "transaction_tax_deductible_amount": "0.00",
        "transaction_type": "V,M",
        "user_id": "638",
        "want_to_anonymous": "No",
        "webhook_trigger_type": "new_transaction"
    }
]


new_transaction (refunds) example


[
    {
        "address": "1234567 Street",
        "associated_activity_IDs": "RD1004460",
        "business_organization_name": "",
        "campaign_name": "Multi Tool Campaign",
        "cause_id": "4809",
        "city": "Nashville",
        "contact_id": "CID638-1000038",
        "country": "US",
        "country_code": "+1",
        "custom_field_status": "false",
        "email": "[email protected]",
        "fee_by_supporter": "N",
        "first_name": "todd",
        "id": "9003",
        "individual_or_business": "Individual",
        "last_name": "valentine",
        "net_received": "0.00",
        "payment_method": "",
        "phone_no_type": "M",
        "phone_number": "1234567890",
        "postal_code": "12345",
        "posted_amount": "0.00",
        "processing_fee": "0.00",
        "settlement_date": "2021-06-30 16:46:10",
        "state": "TN",
        "support_message": "",
        "total_charged_amount": "0.00",
        "total_transaction_amount": "-25.00",
        "transaction_created_date": "2021-06-30 16:46:10",
        "transaction_date": "2021-06-30 16:46:10",
        "transaction_id": "T1143279",
        "transaction_tax_deductible_amount": "0.00",
        "transaction_type": "RD",
        "user_id": "638",
        "want_to_anonymous": "No",
        "webhook_trigger_type": "new_transaction"
    },
    {
        "address": "1234567 Street",
        "associated_activity_IDs": "RD1004461",
        "business_organization_name": "",
        "campaign_name": "Multi Tool Campaign",
        "cause_id": "4809",
        "city": "Nashville",
        "contact_id": "CID638-1000038",
        "country": "US",
        "country_code": "+1",
        "custom_field_status": "false",
        "email": "[email protected]",
        "fee_by_supporter": "N",
        "first_name": "todd",
        "id": "9004",
        "individual_or_business": "Individual",
        "last_name": "valentine",
        "net_received": "0.00",
        "payment_method": "",
        "phone_no_type": "M",
        "phone_number": "1234567890",
        "postal_code": "12345",
        "posted_amount": "0.00",
        "processing_fee": "0.00",
        "settlement_date": "2021-06-30 16:46:11",
        "state": "TN",
        "support_message": "",
        "total_charged_amount": "0.00",
        "total_transaction_amount": "-1.53",
        "transaction_created_date": "2021-06-30 16:46:10",
        "transaction_date": "2021-06-30 16:46:11",
        "transaction_id": "T1143280",
        "transaction_tax_deductible_amount": "0.00",
        "transaction_type": "RD",
        "user_id": "638",
        "want_to_anonymous": "No",
        "webhook_trigger_type": "new_transaction"
    }
]

new_account_credit

[{
    "webhook_record_id": "182",
    "webhook_trigger_type": "new_account_credit",
    "user_id": "638",
    "trace_number": "123",
    "invoice_number": 1501012,
    "pdf_paid_invoice": "https://flipcause.s3.amazonaws.com/uploads/invoice/invoice_1634833054.pdf"",
    "date": "2021-10-21 12:00:00",
    "subscription": "standard",
    "frequency": "",
    "description": "test 2",
    "payment_method": "credit_card",
    "trace_source": "Rev_Invoice_Acct",
    "amount": "6.67",
    "status": "Paid",
    "paid_date": "2021-10-21 12:00:00",
    "acc_initials": "Added by admin",
    "created_date": "2021-10-21 12:17:34",
}]


update_account_credit

[{
    "webhook_record_id": "183",
    "webhook_trigger_type": "update_account_credit",
    "user_id": "638",
    "id": "1012",
    "updated_field": "status",
    "trace_number": "123",
    "invoice_number": 1501012,
    "OLD_status": "Paid",
    "NEW_status": "Unpaid",
    "pdf_unpaid_link": "https://flipcause.s3.amazonaws.com/uploads/invoice/invoice_unpaid_1634835678.pdf"",
    "date": "2021-10-21 12:00:00",
    "subscription": "standard",
    "frequency": "",
    "description": "test 2",
    "payment_method": "credit_card",
    "trace_source": "Rev_Invoice_Acct",
    "amount": "6.67",
    "status": "Unpaid",
    "paid_date": null,
    "acc_initials": "Added by admin",
    "created_date": "2021-10-21 13:01:19",
}]


delete_account_credit

[{
    "webhook_record_id": "184",
    "webhook_trigger_type": "delete_account_credit",
    "user_id": "638",
    "id": "1012",
    "trace_number": "123",
    "invoice_number": 1501012,
    "pdf_unpaid_invoice": "https://flipcause.s3.amazonaws.com/uploads/invoice/invoice_unpaid_1634835678.pdf"",
    "date": "2021-10-21 12:00:00",
    "subscription": "standard",
    "frequency": "",
    "description": "test 2",
    "payment_method": "credit_card",
    "trace_source": "Rev_Invoice_Acct",
    "amount": "6.67",
    "status": "Unpaid",
    "paid_date": null,
    "created_date": "2021-10-21 13:38:28",
}]


Webhook Validation

This functionality is available as an added layer of security if you are developing a custom webhook but is not required.

Before you respond to a webhook, you can verify that the webhook was sent from Flipcause. You can verify the webhook by calculating a digital signature.

Each webhook request includes a base 64-encoded http-x-flipcause-hmac-sha256 header, which is generated using your integration center Signing Secret along with the data sent in the request.

Note: If the Signing Secret is ever compromised, you can “Roll" a new secret in the Webhooks section of the integration center. You will need to remember to update the secret in your own code.

PHP Example

# The following example uses PHP to verify a webhook request:

<?php

# Your Flipcause signing secret, viewable from the Integration Center. In a production environment, set the signing secret as an environment variable to prevent exposing it in code.
define('SIGNING_SECRET', 'whsec_<signing_secret>');

function verify_webhook($data, $hmac_header)
{
  $calculated_hmac = base64_encode(hash_hmac('sha256', $data, SIGNING_SECRET, true));
  return hash_equals($hmac_header, $calculated_hmac);
}

$hmac_header = $_SERVER['http-x-flipcause-hmac-sha256'];
$data = file_get_contents('php://input');
$verified = verify_webhook($data, $hmac_header);

error_log('Webhook verified: '.var_export($verified, true)); // Check error.log to see the result

if ($verified) {
  # Process webhook payload
  # ...
} else {
  http_response_code(401);
}

?>

Compare the computed value to the value in the http-x-flipcause-hmac-sha256 header.

If the HMAC digest and header value match, then the webhook was sent from Flipcause.