What is a webhook?

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.

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. For error responses, or if there was no connection at all, there will be in total 64 retries. If there was no successful response after 64 retries, the webhook will be marked as failed and will not be called again.

We will notify you via problem notification email after 50 failed calls and when marking a webhook as failed.

Retry-After response header

You can also use the Retry-After response header to inform us when to retry the webhook call. This can be used as a form of rate limiting. We accept values in seconds and dates, according to the specification.

Please note that this is only a minimum delay. So if our backoff time is larger than the value of Retry-After, our backoff will take precedence over your value. We will only use your value if it is larger than our regular backoff.

Examples:
Retry-After: 120
Retry-After: Tue, 29 Oct 2024 16:56:32 GMT

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
// ...