{"_id":"571f5e8cd8667f0e00a3c49e","user":"571f5e46d8e3cf1900762b33","version":{"_id":"571f5e8cd8667f0e00a3c49b","hasDoc":true,"__v":12,"hasReference":true,"project":"571f5e8cd8667f0e00a3c498","createdAt":"2016-04-26T12:26:52.312Z","releaseDate":"2016-04-26T12:26:52.312Z","categories":["571f5e8cd8667f0e00a3c49c","571f73cfcb4baa0e00d13a80","571f7451cb4baa0e00d13a88","571f7d2720695f3400f38797","571f7fb0ac2a080e0014c661","571f884be54f2d0e003ebb0a","572200c9ecb38d0e00d80ebd","572c301e7c8eff0e00aaa174","57df91b2c6348d0e0020c452","57e104db9ff1e21900a721ab","57fd04caeaa77f19008b8202","5899c7113514ce0f0014da84"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"__v":13,"project":"571f5e8cd8667f0e00a3c498","category":{"_id":"571f5e8cd8667f0e00a3c49c","version":"571f5e8cd8667f0e00a3c49b","__v":0,"project":"571f5e8cd8667f0e00a3c498","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-04-26T12:26:52.333Z","from_sync":false,"order":1,"slug":"documentation","title":"Webhooks"},"parentDoc":null,"githubsync":"","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-04-26T12:26:52.370Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"With webhooks we can inform external systems if an event occurs (e.g. if a donor is made or if a fundraiser changes the description of his fundraising page).\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Important note:\",\n  \"body\": \"The webhook is called asynchronously after the transaction is completed and the donor is redirected to the success page.\"\n}\n[/block]\nEach webhook call provides two helpful HTTP headers: X-FundraisingBox-Request-Id and X-FundraisingBox-Event.\n\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"X-FundraisingBox-Request-Id\",\n    \"0-1\": \"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.\",\n    \"1-0\": \"X-FundraisingBox-Event\",\n    \"1-1\": \"This header shows the reason why the webhook is called.\\n\\n  * donation.create\\n  * donation.payment\\n  * donation.payment_error\\n\\n\\n\\n\\n  * fundraising_page.create\\n  * fundraising_page.update\\n  * fundraising_page.10_days\\n  * fundraising_page.30_days\\n  * fundraising_page.10_days_left\\n  * fundraising_page.half_goal_reached\\n  * fundraising_page.goal_reached\\n  * fundraising_page.goal_expired\\n\\n\\n  * recurring_payment.create\\n  * recurring_payment.update\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Response, error handling, backoff\"\n}\n[/block]\nIf 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. \n\nAfter 24 hours there will be further calls twice a day until the webhook finally fails after 7 days.\n\nPlease note that this backoff mechanism could be changed in detail.\n[block:api-header]\n{\n  \"title\": \"Transaction webhook\"\n}\n[/block]\nEach 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.\n[block:api-header]\n{\n  \"title\": \"Webhook variantes\"\n}\n[/block]\n  * **[Merge webhook](https://developer.fundraisingbox.com/docs/merge-webhook)**: all stored data\n  * **[Raw webhook](https://developer.fundraisingbox.com/docs/raw-webhook)**: only donation form data \n[block:api-header]\n{\n  \"title\": \"Where to define webhook url\"\n}\n[/block]\nIf your FundraisingBox variant contains webhooks, you can find them in the advanced edit mode of your forms.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/66eb2de-R2shRPIVT2OysTTacc1M_webhook.png\",\n        \"R2shRPIVT2OysTTacc1M_webhook.png\",\n        661,\n        182,\n        \"#e9f0f5\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Fundraising page webhook\"\n}\n[/block]\nWhen 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.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<fb_fundraising_page>\\n  <id type=\\\"integer\\\">2651</id>\\n  <fb_person_id type=\\\"integer\\\">12</fb_person_id>\\n  <fb_project_id type=\\\"integer\\\"/>\\n  <fb_payment_form_project_item_id type=\\\"integer\\\"/>\\n  <fb_fundraising_page_addon_id type=\\\"integer\\\">65</fb_fundraising_page_addon_id>\\n  <image_url><![CDATA[...]]></image_url>\\n  <has_image>false</has_image>\\n  <fundraiser_name>\\n      <![CDATA[Max Mustermann]]>\\n  </fundraiser_name>\\n  <fundraiser_email>\\n      <![CDATA[noreply:::at:::example.com]]>\\n  </fundraiser_email>\\n  <title>\\n      <![CDATA[...]]>\\n  </title>\\n  <description>\\n      <![CDATA[...]]>\\n  </description>\\n  <link>\\n      <![CDATA[...]]>\\n  </link>\\n  <admin_link>\\n      <![CDATA[...]]>\\n  </admin_link>\\n  <goal>250</goal>\\n  <received>100</received>\\n  <donation_count>7</donation_count>\\n  <donation_message>\\n      <![CDATA[...]]>\\n  </donation_message>\\n  <category>sports</category>\\n  <status>active</status>\\n  <expires_at type=\\\"datetime\\\">2016-07-21</expires_at>\\n  <updated_at type=\\\"datetime\\\">2016-04-27 09:35:08</updated_at>\\n  <created_at type=\\\"datetime\\\">2016-04-21 20:48:11</created_at>\\n</fb_fundraising_page>\",\n      \"language\": \"xml\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Security aspects\"\n}\n[/block]\nWe 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](https://en.wikipedia.org/wiki/Basic_access_authentication)\nIf this is the case, please provide us also the login credentials.\n\n\n[block:api-header]\n{\n  \"title\": \"PHP example for processing the push call:\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php \\n// Read in the xml document\\n$xmlStream = fopen(\\\"php://input\\\", \\\"r\\\");\\n$xmlData = stream_get_contents($xmlStream);\\nfclose($xmlStream);\\n \\n// load document and process parameters\\n$xml= simplexml_load_string($xmlData); // provides a php object\\n$amount = $xml->fb_donation->amount\\n// ...\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"what-is-a-webhook","type":"basic","title":"What is a webhook?"}

What is a webhook?


With webhooks we can inform external systems if an event occurs (e.g. if a donor is made or if a fundraiser changes the description of his fundraising page). [block:callout] { "type": "info", "title": "Important note:", "body": "The webhook is called asynchronously after the transaction is completed and the donor is redirected to the success page." } [/block] Each webhook call provides two helpful HTTP headers: X-FundraisingBox-Request-Id and X-FundraisingBox-Event. [block:parameters] { "data": { "0-0": "X-FundraisingBox-Request-Id", "0-1": "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.", "1-0": "X-FundraisingBox-Event", "1-1": "This header shows the reason why the webhook is called.\n\n * donation.create\n * donation.payment\n * donation.payment_error\n\n\n\n\n * fundraising_page.create\n * fundraising_page.update\n * fundraising_page.10_days\n * fundraising_page.30_days\n * fundraising_page.10_days_left\n * fundraising_page.half_goal_reached\n * fundraising_page.goal_reached\n * fundraising_page.goal_expired\n\n\n * recurring_payment.create\n * recurring_payment.update" }, "cols": 2, "rows": 2 } [/block] [block:api-header] { "title": "Response, error handling, backoff" } [/block] 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. [block:api-header] { "title": "Transaction webhook" } [/block] 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. [block:api-header] { "title": "Webhook variantes" } [/block] * **[Merge webhook](https://developer.fundraisingbox.com/docs/merge-webhook)**: all stored data * **[Raw webhook](https://developer.fundraisingbox.com/docs/raw-webhook)**: only donation form data [block:api-header] { "title": "Where to define webhook url" } [/block] If your FundraisingBox variant contains webhooks, you can find them in the advanced edit mode of your forms. [block:image] { "images": [ { "image": [ "https://files.readme.io/66eb2de-R2shRPIVT2OysTTacc1M_webhook.png", "R2shRPIVT2OysTTacc1M_webhook.png", 661, 182, "#e9f0f5" ] } ] } [/block] [block:api-header] { "title": "Fundraising page webhook" } [/block] 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. [block:code] { "codes": [ { "code": "<fb_fundraising_page>\n <id type=\"integer\">2651</id>\n <fb_person_id type=\"integer\">12</fb_person_id>\n <fb_project_id type=\"integer\"/>\n <fb_payment_form_project_item_id type=\"integer\"/>\n <fb_fundraising_page_addon_id type=\"integer\">65</fb_fundraising_page_addon_id>\n <image_url><![CDATA[...]]></image_url>\n <has_image>false</has_image>\n <fundraiser_name>\n <![CDATA[Max Mustermann]]>\n </fundraiser_name>\n <fundraiser_email>\n <![CDATA[noreply@example.com]]>\n </fundraiser_email>\n <title>\n <![CDATA[...]]>\n </title>\n <description>\n <![CDATA[...]]>\n </description>\n <link>\n <![CDATA[...]]>\n </link>\n <admin_link>\n <![CDATA[...]]>\n </admin_link>\n <goal>250</goal>\n <received>100</received>\n <donation_count>7</donation_count>\n <donation_message>\n <![CDATA[...]]>\n </donation_message>\n <category>sports</category>\n <status>active</status>\n <expires_at type=\"datetime\">2016-07-21</expires_at>\n <updated_at type=\"datetime\">2016-04-27 09:35:08</updated_at>\n <created_at type=\"datetime\">2016-04-21 20:48:11</created_at>\n</fb_fundraising_page>", "language": "xml" } ] } [/block] [block:api-header] { "title": "Security aspects" } [/block] 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](https://en.wikipedia.org/wiki/Basic_access_authentication) If this is the case, please provide us also the login credentials. [block:api-header] { "title": "PHP example for processing the push call:" } [/block] [block:code] { "codes": [ { "code": "<?php \n// Read in the xml document\n$xmlStream = fopen(\"php://input\", \"r\");\n$xmlData = stream_get_contents($xmlStream);\nfclose($xmlStream);\n \n// load document and process parameters\n$xml= simplexml_load_string($xmlData); // provides a php object\n$amount = $xml->fb_donation->amount\n// ...", "language": "php" } ] } [/block]