CUSTOM INTEGRATIONS

Introduction and Terminology

With Webhooks you can subscribe to notifications about the donations you receive through ActBlue. When you receive a donation, we will schedule the sending of a notification, which has an HTTPS POST payload, encoded in JSON, to the webhook's secure endpoint URL (read this introduction to webhooks if this terminology is unfamiliar). Webhooks are also available for refunds and cancellations.

Donation data is described in the notifications as contributions from donors to entities. This includes the donor's name, address, employer, and other personal information. Contributions have one or more line items, akin to an item in a shopping cart, each of which specifies a date, a dollar amount, and the receiving entity (an organization that accepts donations through ActBlue). A notification is sent for each line item.

Notifications may include additional information related to these ActBlue features:

  • ActBlue Express users are donors who choose to store their credit card information with ActBlue, to facilitate future donations.
  • ActBlue Express Lane enables ActBlue Express users to donate with a single click.
  • A/B tests let you compare two different variations of a contribution form (e.g. with two different titles) in order to find the one that works best.
  • Refcodes (short for reference codes) are URL parameters that you can add to your contribution form links in order to collect useful data about where your donations are coming from.
  • Smart Recurring allows you to prompt users to make their contribution into a recurring contribution, but with a different amount for recurrences than the initial contribution amount.

Request a Webhook

You can request a new webhook right in the Webhooks Integrations tab of your Dashboard! First you will have to choose the webhook type you need from a dropdown menu. This depends on the service you are trying to connect with, and you should check out our third-party integrations understand which one you will need.

Payloads and Events

Examples

Donations

{
  "donor": {
    "firstname": "Donor",
    "lastname": "Jill",
    "addr1": "253 Klein Turnpike",
    "city": "Somerville",
    "state": "MA",
    "zip": "70409",
    "country": "United States",
    "isEligibleForExpressLane": true,
    "employerData": {
      "employer": "West, Stroman and Thompson",
      "occupation": "Teacher",
      "employerAddr1": "7109 Stoltenberg Run",
      "employerCity": "Hermistonport",
      "employerState": "NH",
      "employerCountry": "United States"
    },
    "email": "vitaehic38@example.com",
    "phone": "925.186.6285 x99996"
  },
  "contribution": {
    "createdAt": "2019-01-18T20:44:25-05:00",
    "orderNumber": "AB00000000",
    "contributionForm": "name-of-contribution-form",
    "refcode": "r1 (DEPRECATED - use refcodes instead)",
    "refcode2": "r2 (DEPRECATED - use refcodes instead)",
    "refcodes": {
      "refcode": "r1",
      "refcode2": "r2",
      "refcodeCustom": "r3"
    },
    "creditCardExpiration": "10/2021",
    "recurringPeriod": "weekly",
    "recurringDuration": 1,
    "weeklyRecurringSunset": null,
    "abTestName": "name_of_ab_Test",
    "isRecurring": "true (DEPRECATED - use recurringPeriod instead)",
    "isPaypal": false,
    "isMobile": true,
    "abTestVariation": "control",
    "isExpress": false,
    "withExpressLane": false,
    "expressSignup": false,
    "uniqueIdentifier": "a4cc36e7-3b22-4741-9c73-852a4794484f (DEPRECATED - use lineitemId instead)",
    "status": "approved",
    "thanksUrl": "url_for_approved_contribution.com",
    "retryUrl": "url_for_declined_contribution.com",
    "textMessageOption": "unknown",
    "giftDeclined": false,
    "giftIdentifier": 1001,
    "shippingName": "Donor Jill",
    "shippingAddr1": "253 Klein Turnpike",
    "shippingCity": "Somerville",
    "shippingState": "MA",
    "shippingZip": "70709",
    "shippingCountry": "USA",
    "smartBoostAmount": "2.5",
    "customFields": [
      {
        "label": "Favorite color?",
        "answer": "blue"
      }
    ],
    "merchandise": [
      {
        "name": "T-Shirt",
        "itemId": 123242,
        "details": {
          "color": "Blue",
          "size": "Small"
        }
      },
      {
        "name": "T-Shirt",
        "itemId": 123242,
        "details": {
          "color": "Blue",
          "size": "Medium"
        }
      },
      {
        "name": "Sticker",
        "itemId": 234231,
        "details": null
      }
    ],
    "bump_your_recurring": [
      {
        "bumpRecurringLink": "https://secure.actblue.com/my-express/contributions/recurring/ABORDERNUMBER/bump",
        "recurringUpsellSeen": true,
        "recurringUpsellAccepted": false
      }
    ]
  },
  "lineitems": [
    {
      "sequence": 0,
      "entityId": 99999,
      "fecId": null,
      "committeeName": "LoremIpsum for Congress",
      "amount": "25.9",
      "recurringAmount": "15.7",
      "paidAt": "2017-10-03T13:48:26-04:00",
      "paymentId": "0123456 (DEPRECATED - use lineitemId if you need a unique identifier for each event notification)",
      "lineitemId": 99999999
    }
  ],
  "form": {
    "name": "xyz-form",
    "kind": "page",
    "managingEntityName": "Lorem Ipsum",
    "managingEntityCommitteeName": null,
    "ownerEmail": null
  }
}

Refunds

{
  "donor": {
    "firstname": "Donor",
    "lastname": "Jill",
    "addr1": "253 Klein Turnpike",
    "city": "Somerville",
    "state": "MA",
    "zip": "70409",
    "country": "United States",
    "isEligibleForExpressLane": true,
    "employerData": {
      "employer": "West, Stroman and Thompson",
      "occupation": "Teacher",
      "employerAddr1": "7109 Stoltenberg Run",
      "employerCity": "Hermistonport",
      "employerState": "NH",
      "employerCountry": "United States"
    },
    "email": "vitaehic38@example.com",
    "phone": "925.186.6285 x99996"
  },
  "contribution": {
    "createdAt": "2019-01-18T20:44:25-05:00",
    "orderNumber": "AB00000000",
    "contributionForm": "name-of-contribution-form",
    "refcode": "r1 (DEPRECATED - use refcodes instead)",
    "refcode2": "r2 (DEPRECATED - use refcodes instead)",
    "refcodes": {
      "refcode": "r1",
      "refcode2": "r2",
      "refcodeCustom": "r3"
    },
    "creditCardExpiration": "10/2021",
    "recurringPeriod": "weekly",
    "recurringDuration": 1,
    "weeklyRecurringSunset": null,
    "abTestName": "name_of_ab_Test",
    "isRecurring": "true (DEPRECATED - use recurringPeriod instead)",
    "isPaypal": false,
    "isMobile": true,
    "abTestVariation": "control",
    "isExpress": false,
    "withExpressLane": false,
    "expressSignup": false,
    "uniqueIdentifier": "a4cc36e7-3b22-4741-9c73-852a4794484f (DEPRECATED - use lineitemId instead)",
    "status": "approved",
    "thanksUrl": "url_for_approved_contribution.com",
    "retryUrl": "url_for_declined_contribution.com",
    "textMessageOption": "unknown",
    "giftDeclined": false,
    "giftIdentifier": 1001,
    "shippingName": "Donor Jill",
    "shippingAddr1": "253 Klein Turnpike",
    "shippingCity": "Somerville",
    "shippingState": "MA",
    "shippingZip": "70709",
    "shippingCountry": "USA",
    "smartBoostAmount": "2.5",
    "customFields": [
      {
        "label": "Favorite color?",
        "answer": "blue"
      }
    ],
    "merchandise": [
      {
        "name": "T-Shirt",
        "itemId": 123242,
        "details": {
          "color": "Blue",
          "size": "Small"
        }
      },
      {
        "name": "T-Shirt",
        "itemId": 123242,
        "details": {
          "color": "Blue",
          "size": "Medium"
        }
      },
      {
        "name": "Sticker",
        "itemId": 234231,
        "details": null
      }
    ],
    "bump_your_recurring": [
      {
        "bumpRecurringLink": "https://secure.actblue.com/my-express/contributions/recurring/ABORDERNUMBER/bump",
        "recurringUpsellSeen": true,
        "recurringUpsellAccepted": false
      }
    ]
  },
  "lineitems": [
    {
      "sequence": 0,
      "entityId": 99999,
      "fecId": null,
      "committeeName": "LoremIpsum for Congress",
      "amount": "25.9",
      "recurringAmount": "15.7",
      "paidAt": "2017-10-03T13:48:26-04:00",
      "paymentId": "0123456 (DEPRECATED - use lineitemId if you need a unique identifier for each event notification)",
      "lineitemId": 99999999,
      "refundedAt": "2017-10-03T13:48:26-04:00",
      "disbursedAt": null,
      "recoveredAt": null
    }
  ],
  "form": {
    "name": "xyz-form",
    "kind": "page",
    "managingEntityName": "Lorem Ipsum",
    "managingEntityCommitteeName": null,
    "ownerEmail": null
  }
}

Cancellations

{
  "donor": {
    "firstname": "Donor",
    "lastname": "Jill",
    "addr1": "253 Klein Turnpike",
    "city": "Somerville",
    "state": "MA",
    "zip": "70409",
    "country": "United States",
    "isEligibleForExpressLane": true,
    "employerData": {
      "employer": "West, Stroman and Thompson",
      "occupation": "Teacher",
      "employerAddr1": "7109 Stoltenberg Run",
      "employerCity": "Hermistonport",
      "employerState": "NH",
      "employerCountry": "United States"
    },
    "email": "vitaehic38@example.com",
    "phone": "925.186.6285 x99996"
  },
  "contribution": {
    "createdAt": "2019-01-18T20:44:25-05:00",
    "orderNumber": "AB00000000",
    "contributionForm": "name-of-contribution-form",
    "refcode": "r1 (DEPRECATED - use refcodes instead)",
    "refcode2": "r2 (DEPRECATED - use refcodes instead)",
    "refcodes": {
      "refcode": "r1",
      "refcode2": "r2",
      "refcodeCustom": "r3"
    },
    "creditCardExpiration": "10/2021",
    "recurringPeriod": "weekly",
    "recurringDuration": 1,
    "weeklyRecurringSunset": null,
    "abTestName": "name_of_ab_Test",
    "isRecurring": "true (DEPRECATED - use recurringPeriod instead)",
    "isPaypal": false,
    "isMobile": true,
    "abTestVariation": "control",
    "isExpress": false,
    "withExpressLane": false,
    "expressSignup": false,
    "uniqueIdentifier": "a4cc36e7-3b22-4741-9c73-852a4794484f",
    "status": "approved",
    "thanksUrl": null,
    "retryUrl": null,
    "textMessageOption": "unknown",
    "giftDeclined": false,
    "giftIdentifier": 1001,
    "shippingName": "Donor Jill",
    "shippingAddr1": "253 Klein Turnpike",
    "shippingCity": "Somerville",
    "shippingState": "MA",
    "shippingZip": "70709",
    "shippingCountry": "USA",
    "smartBoostAmount": "2.5",
    "customFields": [
      {
        "label": "Favorite color?",
        "answer": "blue"
      }
    ],
    "cancelledAt": "2017-10-03T13:48:26-04:00",
    "recurringType": "initially weekly",
    "recurCompleted": 5,
    "recurPledged": "3"
  },
  "lineitems": [
    {
      "sequence": 0,
      "entityId": 99999,
      "fecId": null,
      "committeeName": "LoremIpsum for Congress",
      "amount": "25.9",
      "recurringAmount": "15.7",
      "paidAt": "2017-10-03T13:48:26-04:00",
      "paymentId": "0123456 (DEPRECATED - use lineitemId if you need a unique identifier for each event notification)",
      "lineitemId": 99999999
    }
  ],
  "form": {
    "name": "xyz-form",
    "kind": "page",
    "managingEntityName": "Lorem Ipsum",
    "managingEntityCommitteeName": null,
    "ownerEmail": null
  }
}

Event Types and Descriptions

We have webhooks available for three different types of events, and can set up one or more for you:

  • Donations
  • Refunds
  • Cancellations

Donations

donor

Key Description Nullable
firstname Donor's first name
lastname Donor's last name
addr1 Donor's street addresss*
city Donor's city*
state Donor's state*
zip Donor's zip code*
country Donor's country
isEligibleForExpressLane Whether the donor is eligible to donate through Express Lane
email Donor's email**
phone Donor's phone**

employerData (nested under donor)

Key Description Nullable
employer Donor's employer
occupation Donor's occuption
employerAddr1 Donor's employer's address
employerCity Donor's employer's city
employerState Donor's employer's state
employerCountry Donor's employer's country

contribution

Key Description Nullable
createdAt ISO 8601 timestamp for the contribution (e.g. 2017-10-03T13:48:26-04:00)
orderNumber The ActBlue order number (e.g. AB999999)
contributionForm A unique identifier you assign to the contribution form (e.g. xyz-form)
refcode DEPRECATED - use refcodes instead. An optional tracking code you can put in links to your contribution form
refcode2 DEPRECATED - use refcodes instead. An optional tracking code you can put in links to your contribution form
refcodes An object with the names of your refcodes (tracking codes from form links) as the keys
creditCardExpiration The month and year of expiration (e.g. 10/2021) (null for PayPal contributions)
recurringPeriod Possible values are: 'once' (for a one-time contribution), 'weekly', or 'monthly'
recurringDuration For monthly recurring contributions, the total number of months - possible values are a number or the word 'infinite'
abTestName If you run an A/B Test for your form, the name of the test (e.g. branded_layout)
isRecurring DEPRECATED - use recurringPeriod instead. Whether this is a monthly recurring contribution
weeklyRecurringSunset For weekly recurring contributions, the last date that the contribution will recur (e.g. '2020-05-01')
isPaypal Whether the contribution was made with paypal (true or false)
isMobile Whether the contribution was made on a mobile device (true or false)
abTestVariation If you run an A/B Test for your form, the name of the variation shown (e.g. control)
isExpress Whether the donor is an ActBlue Express user (true or false)
withExpressLane Whether the contribution was made through ActblueExpress Lane (true or false)
expressSignup Whether the donor chose to sign up for ActBlue express after making the contribution (true or false)
uniqueIdentifier DEPRECATED - use lineitemId if you need a unique identifier for each event notification.
status Possible values are: approved, declined, or pending
thanksUrl For an approved contribution: URL of the thank-you page shown to the donor (optional***)
retryUrl For a declined contribution: URL where the donor can update the payment source (optional***)
textMessageOption Indicates whether or not the donor opted in to receive text messages - possible values: unknown, opt_in, opt_out. If you would like to use donor numbers for texting, please contact support@actblue.com. If donors are not asked for texting permission, the value will be 'unknown'
giftDeclined For a form with enabled recurring gift promotion, the donor can choose to opt-out of the gift (optional)
giftIdentifier For a form with enabled recurring gift promotion, the unique identifier you assign to the gift
shippingName For a form with enabled recurring gift promotion, the gift donor's name
shippingAddr1 For a form with enabled recurring gift promotion, the donor’s provided shipping address
shippingCity For a form with enabled recurring gift promotion, the donor’s provided city
shippingState For a form with enabled recurring gift promotion, the donor's provided state
shippingZip For a form with enabled recurring gift promotion, the donor's provided zip code
shippingCountry For a form with enabled recurring gift promotion, the donor's provided country
smartBoostAmount For a form with enabled smart boost post donation upsell, the amount upsold

customFields (nested under contribution)

Key Description Nullable
label The label of a custom field for the contribution, as it was displayed at the time the contribution was made
answer The donor's answer to the custom field question

merchandise (nested under contribution)

Key Description Nullable
name Name of the item purchased. Same name displayed to the user in the form
details a JSON object containing details about the variation of the item (such as different sizes, colors) that the user purchased, if the item has variations. These variations are defined by the form creator when they add items for sale to the form. If the item does not have variations, this field will be null.
itemId a numeric identifier of the type of item being purchased e.g. a t-shirt or a sticker. This identifier does not change for different variants of the same item - so a T-shirt with { "size": "small" } in the details object would have the same itemId as a T-shirt with { "size": "large" }. This identifier is unique across all items on ActBlue.

bumpYourRecurring (nested under contribution)

Key Description Nullable
bumpRecurringLink Custom link for an individual express donor that will suggest bump amounts based on the current recurring contribution amount
recurringUpsellSeen indicates that a donor has landed on the bump request page
recurringUpsellAccepted indicates that the donor has confirmed to bump to a higher amount

lineItems

Key Description Nullable
sequence A zero-based count of the recurrences for this line item ('0' for one-time contributions)
entityId A unique integer identifier for the entity (e.g. 99999)
fecId The FEC ID for the entity (e.g. PENDING,999999999;)
committeeName A descriptive name of the entity (e.g. Peter Gibbons for Congress)
amount The USD amount of the contribution, in decimal form (e.g. 25.9)
recurringAmount For recurring contributions, the dollar amount that will be processed for each recurrence, in decimal form (e.g. 25.9). This can be different than the 'amount' field when Smart Recurring is used. Will be null for one time contributions.
paidAt An ISO 8601 timestamp (e.g. 2017-10-03T13:48:26-04:00)
paymentId DEPRECATED - use lineitemId if you need a unique identifier for each event notification.
lineitemId A unique integer identifier for the line item (e.g. 99999999)

form

Key Description Nullable
name A unique identifier you assign to the contribution form (e.g. xyz-form)
kind Indicates the type of form - possible values are page (the default), merchandise, event, embed, or autogenerated (created by donors via donor admin tools)
managingEntityName For managed forms, the display name of the entity that manages the form
managingEntityCommitteeName For managed forms, the committee name of the entity that manages the form
ownerEmail For community forms, the email of the user who owns the form

* For compliance purposes, ActBlue required a verifiable donor for most types of organizations

** Donors are required to provide and email when contributing, but when a recipient organization does not manage the contribution form, donors have the option to withold sharing on their email and phone number.

*** thanksUrl and retryUrl are conditional fields:

  • If the status is "approved" a thanksUrl is included, which is the URL of the page shown to the donor after completing their contribution.
  • If the status is "declined" and your webhook is configured to notify for declined contributions, a retryUrl is included, which is the URL the donor can use to update the payment source and try again.
  • If the status is "pending" neither a thanksUrl nor a retryUrl is included.

Refund

lineItems

Key Description Nullable
refundedAt Timestamp of when ActBlue refunded the donor
disbursedAt Timestamp of when the funds were disbursed to the entity null if refunded before disbursement
recoveredAt Timestamp of when the funds were recovered from the entity; this date should match the check date that the recovered contribution was subtracted from. null if refunded before disbursement or not recovered yet

Cancellation

contribution

Key Description Nullable
cancelledAt Timestamp of the cancellation
recurringType Possible values are: 'initially forever', 'initially monthly', 'initially weekly', 'initially monthly adjustable'
recurCompleted The number of recurring contributions that were completed prior to the cancellation, including the first
recurPledged The number of contributions the donor had pledged, including the first

Configuring your secure Endpoints server and testing your Webhook

  1. To configure a server to receive notifications from ActBlue webhooks, you can start with the same steps used for receiving notifications from GitHub webhooks. However, we also require the use of an HTTPS (secure) server.
  2. ActBlue webhooks include Basic Authentication credentials when sending a notification to your server. Please configure your server for Basic Authentication, and let us know the username and password to use.
  3. We may add new data to the JSON payloads described above without warning in the future. Make sure your code can handle new fields without error.
  4. We recommend you store and acknowledge (with a 200 status code or similar response) the JSON payload before doing any intensive processing, to ensure your server can handle a high volume of notifications. For very active entities at peak times (think Bernie for President on national TV) we may send thousands of requests per minute. Also, for any "backfills" you may want (see below), the volume of incoming requests can be very high, even if your volume is normally low.
  5. Let us know when you are ready to receive a test notification, and we can send one to you!

Handling of failed Event Notifications

We monitor the HTTP status code of the responses we receive to determine the status of notifications, and whether to retry. For retries, we will retry a notification 10 times before logging it as failed. The length of time will grow between each retry attempt.

  • 2xx responses: we will log the notification as successful in our records.
  • 3xx responses: for security reasons we do not support redirects. We wil log it as a notification that will be retried.
  • 4xx responses: we will log it as failed and not retry sending it, as a 4xx response indicates you received the message but will not process it.
  • 5xx responses: we wil log it as a notification that will be retried, as a 5xx response indicates a temporary problem with your server.

If your server responds with numerous responses other than 2xx responses within a short period of time, we will pause sending any notifications for several hours, and then try again (paused notifications will be queued for when sending resumes).

Sending notifications for donations in the past

If you are setting up a webhook for the first time, and have previous donations with ActBlue for which you would like to receive notifications, we can send them to you with our "backfill" feature. Please request a backfill date when you request a webhook in your dashboard.

Sending test notifications

This tool is intended for testing out new custom integrations with the ActBlue Default webhook. It will send an example webhook payload to the endpoint URL you specify The data contained in this webhook payload is mock data and *not actual contribution data*. We recommend you remove mock data from any live service after your test. If you have any questions about this tool please contact integrations@actbluetech.com