Webhook API

You can use webhooks to get notified of new donations, or of changes to existing donations.

The webhook API is designed to be integrated in your CRM system.

No recurring donations, yet!

Please note, that this api is not yet fully optimized for recurring donations. A donation that is created as part of a recurring donation will be send just like any other donation. Any information about interval and such is not yet implemented.

Changelog

How to receive webhooks

To receive a webhook, you need to set up a web page that can receive POST requests with a JSON payload. You then configure that URL in your account, and it will get called every time an event occurs.

Webhooks must use https encryption, because the events contain sensitive user data.

There are two delivery methods available:

Delivery method Description Target system
JSON body (default) The payload is sent with the POST body as JSON. Recommended for most systems.
JSON URL param The payload is appended to the request URL as a URL-encoded json param. Recommended for CiviCRM with the “Spendenformular Direkt”-Extension.

Responding to a webhook

To acknowledge that you received a webhook correctly, you must return a 2xx HTTP status code. Any other response code, including 3xx redirects and “Not modified” responses are treated as a failure.

If you do not acknowledge the webhook, we’ll retry to deliver the webhook. The first retry will happen within a couple of seconds, with increasing steps up to multiple hours. After 25 failed attempts we will stop retrying and you cannot manually re-try the webhook, though you can still use our CSV download feature to get your data.

Webhook event data

Each event contains the following information:

field type example description
id string 034661d1-0db1-4d55-b601-ce0ff91dd227 Unique id of the webhook event. Stays the same for retries.
timestamp integer 1498813415 Unix timestamp (UTC) for this webhook
type string new_donation Type of the event. Valid types are currently new_donation and revocation.
data hash See below. JSON hash with the event data. Contents depend on the type of event received.
api_version string v1 Version number of the callback API. Fow now always ‘v1’

Event “new_donation”-data

This event is sent each time a new donation is made through the form.

field type example description
donation_id string 034661d1-0db1-4d55-b601-ce0ff91dd227 UUID of the donation
form_id string 4ba389c3-b835-4679-af84-6eeaf9dec15b UUID of the form that were used for the donation
created_at integer 1498813399 Unix timestamp (UTC)
updated_at integer 1498813499 Unix timestamp (UTC)
confirmed_at integer 1498813499 Unix timestamp (UTC)
amount_currency string EUR The donated amount currency (‘EUR’, ‘USD’ or ‘GBP’)
amount_in_cents integer 2342 The donated amount in cents
attribution string rabbit-elementary Label chosen by user. Configurable in the backoffice. For further reference.
newsletter bool true Indicates if the user has consented to receive newsletters
email string gudrun@example.com The email address of the donor
company_name string gut.org gAG Company name. Is empty for a personal donation
first_name string Gudrun First name of the donor
last_name string Gutmensch Last name of the donor
street string Schlesische Str. 26 Street address of the donor
zip string 10997 Zip code of the donor
city string Berlin City of the donor
country string DE 2-Letter country code for the donor
payment_method string sepa Payment method. For example sepa, creditcard or paypal
message string Bitte sendet mir eure Broschüre zu E… Message by the donor to the support team.

Example

{
  "id": "034661d1-0db1-4d55-b601-ce0ff91dd227",
  "timestamp": 1498813415,
  "type": "new_donation",
  "api_version": "v1",
  "data": {
    "donation_id": "034661d1-0db1-4d55-b601-ce0ff91dd227",
    "form_id": "4ba389c3-b835-4679-af84-6eeaf9dec15b",
    "created_at": 1498813399,
    "updated_at": 1498813499,
    "confirmed_at": 1498813499,
    "amount_currency": "EUR",
    "amount_in_cents": 2342,
    "attribution": "rabbit-elementary",
    "email": "gudrun@example.com",
    "newsletter": true,
    "company_name": "gut.org gAG",
    "first_name": "Gudrun",
    "last_name": "Gutmensch",
    "street": "Schlesische Str. 26",
    "zip": "10997",
    "city": "Berlin",
    "country": "DE",
    "payment_method": "sepa",
    "message": "Bitte sendet mir eure Broschüre zu Erbschaftsspenden zu.\nDanke und viele Grüße\nGrudrun"
  }
}

Event “revocation”-data

This event is sent each time a donation is revoked for any reason (bookback, chargeback, etc.)

field type example description
donation_id string 034661d1-0db1-4d55-b601-ce0ff91dd227 UUID of the donation
form_id string 4ba389c3-b835-4679-af84-6eeaf9dec15b UUID of the form that was used for the donation
foreign_id string xyz Foreign id, if provided by you
created_at integer 1498813399 Unix timestamp (UTC)
updated_at integer 1498913399 Unix timestamp (UTC)
confirmed_at integer 1498813499 Unix timestamp (UTC)
revoked_at integer 1498913399 Unix timestamp (UTC)

Example

{
  "id": "034661d1-0db1-4d55-b601-ce0ff91dd227",
  "timestamp": 1498813415,
  "type": "revocation",
  "api_version": "v1",
  "data": {
    "donation_id": "034661d1-0db1-4d55-b601-ce0ff91dd227",
    "form_id": "4ba389c3-b835-4679-af84-6eeaf9dec15b",
    "created_at": 1498813399,
    "updated_at": 1498913399,
    "confirmed_at": 1498813499,
    "revoked_at": 1498913399,
  }
}

Returning data to a webhook

Your response may optionally contain JSON in order to pass information back to our server.

Currently the only parameter supported is foreign_id. With this parameter you can add your own id to a donation.

The foreign_id will be sent in all webhooks once set, so that you can use it to look up objects in your own database.

Example

{
  "foreign_id": "my_unique_id"
}

Checking signatures

Each request will contain a signature in a header field. You can use that to verify that the callback actually originates from betterplace.

The signature looks like this:

XFORM-Signature: t=1498813415,
    sig=ecfc290158b675c1e3851551d65c9f534c71b90265de525a862ca22b9bb86138

The signature is a SHA256 HMAC. The value t in the signature is a timestamp while sig is the actual signature.

To verify the signature, you need to: