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 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[[email protected]]]>
</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
// ...