With webhooks we can inform external systems if an event occurs (e.g. if a donation is made or if a fundraiser changes the description of his fundraising page).

📘
Important note:
The webhook is called asynchronously after the transaction is completed and the donor is redirected to the success page.

Each webhook call provides two helpful HTTP headers: X-FundraisingBox-Request-Id and X-FundraisingBox-Event.

X-FundraisingBox-Request-Id

This is an unique id of the request. Actually every webhook is only send once. There are only some circumstances where a webhook is send multiple times. With the X-FundraisingBox-Request-Id you can find out if there was the same webhook before.

X-FundraisingBox-Event

This header shows the reason why the webhook is called.

online_donation.create (JSON only)
donation.create (XML only)
donation.recurrent (JSON only)
donation.payment
donation.payment_error

person.create (JSON only)
person.update (JSON only)
person.delete (JSON only)
person.restore (JSON only)

fundraising_page.create
fundraising_page.update
fundraising_page.10_days
fundraising_page.30_days
fundraising_page.10_days_left
fundraising_page.half_goal_reached
fundraising_page.goal_reached
fundraising_page.expired

recurring_payment.create (JSON only)
recurring_payment.update (JSON only)
recurring_payment.delete (JSON only)

receipt.create (JSON only)
receipt.delete (JSON only)
receipt.restore (JSON only)
receipt.invalidate (JSON only)

Response, error handling, backoff

If you receive a webhook call your system must respond with a valid 2xx HTTP response code. Otherwise the FundraisingBox assumes that the transfer failed. In this case there are several next tries. Currently there are some further tries every minute followed by hourly calls.

After 24 hours there will be further calls twice a day until the webhook finally fails after 7 days.

Please note that this backoff mechanism could be changed in detail.

Transaction webhook

Each transaction can be synchronized with an external webservice. This can be for instance a mobile or facebook app or an external donor database. For that several so called webhooks can be defined for each donation form. After each transaction a xml document is sent to a given webhook url. It contains all collected data for person, donation, sepa mandate and recurring payment.

Webhook variantes

Merge webhook: all stored data
Raw webhook: only donation form data

Where to define webhook url

Please contact our support to add webhook urls for your account.

Fundraising page webhook

When a fundraising page is created or when it is changed you can be informed by a webhook. Please provide one or more URLs at the fundraising tool configuration at your FundraisingBox settings. Then the following XML is pushed as POST request to these URLs every time a fundraising page is created/updated.

<fb_fundraising_page>
  <id type="integer">2651</id>
  <fb_person_id type="integer">12</fb_person_id>
  <fb_project_id type="integer"/>
  <fb_payment_form_project_item_id type="integer"/>
  <fb_fundraising_page_addon_id type="integer">65</fb_fundraising_page_addon_id>
  <image_url><![CDATA[...]]></image_url>
  <has_image>false</has_image>
  <fundraiser_name>
      <![CDATA[Max Mustermann]]>
  </fundraiser_name>
  <fundraiser_email>
      <![CDATA[noreply@example.com]]>
  </fundraiser_email>
  <title>
      <![CDATA[...]]>
  </title>
  <description>
      <![CDATA[...]]>
  </description>
  <link>
      <![CDATA[...]]>
  </link>
  <admin_link>
      <![CDATA[...]]>
  </admin_link>
  <goal>250</goal>
  <received>100</received>
  <donation_count>7</donation_count>
  <donation_message>
      <![CDATA[...]]>
  </donation_message>
  <category>sports</category>
  <status>active</status>
  <expires_at type="datetime">2016-07-21</expires_at>
  <updated_at type="datetime">2016-04-27 09:35:08</updated_at>
  <created_at type="datetime">2016-04-21 20:48:11</created_at>
</fb_fundraising_page>

Security aspects

We recommend that you use a SSL secured URL. In addition you can use „Basic access authentication“ to restrict the access to your url. See also: https://en.wikipedia.org/wiki/Basic_access_authentication
If this is the case, please provide us also the login credentials.

PHP example for processing the push call:

<?php 
// Read in the xml document
$xmlStream = fopen("php://input", "r");
$xmlData = stream_get_contents($xmlStream);
fclose($xmlStream);
 
// load document and process parameters
$xml= simplexml_load_string($xmlData); // provides a php object
$amount = $xml->fb_donation->amount
// ...