Webhooks

  1. Introduction and terminology
  2. Request a webhook
  3. Events and payloads
  4. Configuring your secure endpoint server and testing your webhook
  5. Handling of failed event notifications
  6. Sending notifications for donations in the past

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:

Request a webhook

Our Outreach team will work with you to set up a webhook. We will need the following information to configure a webhook for you:

Events and payloads

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

Donations annotated payload

{
  "donor": {
    "firstname": "The donor's first name (a required field)",
    "lastname": "The donor's last name (a required field)",
    "addr1": "The donor's street address (a required field*)",
    "city": "The donor's city (a required field*)",
    "state": "The donor's state or province (a required field*)",
    "zip": "The donor's zip or postal code (a required field*)",
    "country": "The donor's country (a required field*)",
    "email": "The donor's email (a required field)",
    "phone": "The donor's phone number (an optional field)",
    "isEligibleForExpressLane": "Whether the donor is eligible to donate through ActBlue Express Lane (true or false)",
    "employerData": {
      "employer": "The donor's employer (an optional field)",
      "occupation": "The donor's occupation (an optional field)",
      "employerAddr1": "The donor's employer's street address (an optional field)",
      "employerCity": "The donor's employer's city (an optional field)",
      "employerState": "The donor's employer's state or province (an optional field)",
      "employerCountry": "The donor's employer's country (an optional field)"
    }
  },
  "contribution": {
    "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": "An optional tracking code you can put in email links to your contribution form (e.g. act-now)",
    "refcode2": "An optional tracking code you can put in email links to your contribution form (e.g. act-now-2)",
    "creditCardExpiration": "The month and year of expiration (e.g. 10/2021)",
    "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 (true or false)",
    "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 ActBlue Express Lane (true or false)",
    "expressSignup": "Whether the donor chose to sign up for ActBlue Express after making this contribution (true or false)",
    "uniqueIdentifier": "e.g. a4cc36e7-3b22-4741-9c73-852a4794484f",
    "status": "Possible values are: approved, declined, or pending",
    "thanksUrl": "or retryUrl, or neither. See ** below"
  },
  "lineitems": [
    {
      "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; can be null)",
      "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)",
      "paidAt": "An ISO 8601 timestamp (e.g. 2017-10-03T13:48:26-04:00)",
      "lineitemId": "A unique integer identifier for the line item (e.g. 99999999)"
    }
  ]
}

* For compliance purposes, ActBlue requires a verifiable donor address for most types of organizations. Please contact us if you have any questions.

** thanksUrl and retryUrl are conditional fields:

Refunds annotated payload

The payload for refund notifications is identical to donations, with the addition of the following fields under lineitems:

{
  "refundedAt": "Timestamp of when ActBlue refunded the donor (e.g. 2017-10-03T13:48:26-04:00)",
  "disbursedAt": "Timestamp of when the funds were disbursed to the entity (null if refunded before disbursement)",
  "recoveredAt": "Timestamp of when the funds were recovered (null if refunded before disbursement or not recovered yet)"
}

Cancellations annotated payload

The notification payload for when a recurring donation is canceled is identical to donations, with the addition of the following fields under contribution, and there is no thanksUrl:

{
  "cancelledAt": "Timestamp of the cancellation (e.g. 2017-10-03T13:48:26-04:00)",
  "recurringType": "Possible values are: forever, monthly, weekly, 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 endpoint 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.

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 contact us for assistance.