{"_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,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-04-26T12:26:52.370Z","link_external":false,"link_url":"","githubsync":"","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\": \"warning\",\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[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"X-FundraisingBox-Request-Id\",\n    \"1-0\": \"X-FundraisingBox-Event\",\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-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  * 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  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\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\n#Webhook variantes\n\n  *     **[Merge webhook](merge-webhook)**: all stored data\n  *     **[Raw webhook](raw-webhook)**: only donation form data\n\n#Where to define webhook url\n\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/R2shRPIVT2OysTTacc1M_webhook.png\",\n        \"webhook.png\",\n        \"661\",\n        \"182\",\n        \"#3d5873\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\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  \"type\": \"basic\",\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\nIf this is the case, please provide us also the login credentials.\n\n#PHP example for processing the push call:\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": "warning", "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", "1-0": "X-FundraisingBox-Event", "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-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 * 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" }, "cols": 2, "rows": 2 } [/block] [block:api-header] { "type": "basic", "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. #Webhook variantes * **[Merge webhook](merge-webhook)**: all stored data * **[Raw webhook](raw-webhook)**: only donation form data #Where to define webhook url 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/R2shRPIVT2OysTTacc1M_webhook.png", "webhook.png", "661", "182", "#3d5873", "" ] } ] } [/block] [block:api-header] { "type": "basic", "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] { "type": "basic", "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 If this is the case, please provide us also the login credentials. #PHP example for processing the push call: [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]