View source for Tracking Webhooks

{{TOCright}}

==What are Tracking Webhooks?==
Tracking Webhooks will let you set a script that will be called after each registration in your event with all relevant information. You choose whether the script should be called from the user's browser or server-to-server. They are extremely easy to use for things like:
*- calling your e-commerce tracking / website tracking ([[Tracking_Webhooks#Conversion_tracking_sample|Conversion tracking sample]])
*- saving ticket buyers' information into your own database or CRM
*- sending automated emails and additional files to ticket buyers after their purchase
*- a lot more...

==How does it work?==
To enable tracking webhooks, go to https://www.xing-events.com/mycenter/events.html, select the event you would like to enable the ticketshop callback for and go to the "Tracking" menu item. 
There you find three integration methods for the Ticketshop callback:
* <b>No callback</b> - The callback is disabled.
* <b>Browser call</b> - After clicking the "Buy Tickets" button, a HTTP POST request will be sent from the user's browser to the specified URL in the background. Make sure that the URL begins with <tt>https://</tt>. Otherwise the user will see a 'Mixed-Content' error. This integration method is not as reliable as the server call.
* <b>Server call</b> (<b>recommended</b>) - After clicking the "Buy Tickets" button, a HTTP POST request will be sent from the XING Events server to the specified URL. The HTTP code and the return value of your page will be stored and can be retrieved in the data export of your event (at "Data export" create a new report and select the "Webhook HTTP status" and/or "Webhook return value" on the "payment" tab). In case the provided URL can not be reached the server will retry up to ten times to open the page (with a 10 minute delay each time). If the page can not be reached after the tenth try it will give up and you can see the HTTP error in your reports. 

[[Image:Webhooks.png]]

==How can I test my implementation?==
The webhook is triggered exactly the same way if the event is still in draft mode. This allows you to test your implementation by doing test purchases in your event while it is in draft. That gives you time to fix possible issues before going live with your event and start selling real tickets.

== Provided parameters ==
The POST data contains the following parameters (if available):
{| cellspacing="0" cellpadding="2" border="0" style="width: 935px;"
|-
! bgcolor="#cccccc" align="left" scope="col" | Parameter<br> 
! bgcolor="#cccccc" align="left" scope="col" | Type<br> 
! bgcolor="#cccccc" align="left" scope="col" | Description<br>
! bgcolor="#cccccc" align="left" scope="col" | <br>
|-valign="top"
| <b>Event parameters</b>
| 
| 
| 
|-valign="top"
| eventId
| [[REST_API_Formats#Integer|Integer]]
| The internal database id of the event.
| 
|-valign="top"
| eventIdentifier
| [[REST_API_Formats#String|String]]
| The public identifier of the event. The event page will be accessible at <tt>www.xing-events.com/&lt;identifier&gt;.html.</tt><br>
| 
|-valign="top"
| eventTitle
| [[REST_API_Formats#String|String]]
| The title of the event.
| 
|-valign="top"
| eventType
| [[REST_API_Formats#String|String]] 
| Whether the event is a registration-event (EVENT_TYPE_REGISTRATION) or a ticketshop-event (EVENT_TYPE_TICKETSHOP)
| 
|-valign="top"
| partnerIdentifier
| [[REST_API_Formats#String|String]]
| The identifier of the partner.
| 
|-valign="top"
| <b>Payment parameters</b>  
| 
| 
| 
|-valign="top"
| paymentId
| [[REST_API_Formats#Integer|Integer]]
| The internal id of the payment.
| 
|-valign="top"
| paymentFirstName
| [[REST_API_Formats#String|String]]
| First name of the ticket buyer
| 
|-valign="top"
| paymentLastName
| [[REST_API_Formats#String|String]]
| Last name of the ticket buyer
| 
|-valign="top"
| paymentEmail
| [[REST_API_Formats#String|String]]
| Email address of the ticket buyer
| 
|-valign="top"
| paymentTelephone
| [[REST_API_Formats#String|String]]
| Telephone number of the ticket buyer (if provided)
|
|-valign="top"
| paymentIdentifier
| [[REST_API_Formats#String|String]]
| The invoice number of the payment. Will only be generated, if the total amount of the payment is greater than zero.
| 
|-valign="top"
| paymentDiscountCode
| [[REST_API_Formats#String|String]]
| The discount/promotion code used for this purchase. If no discount code is used, this parameter will not be send.
| 
|-valign="top"
| paymentValue
| [[REST_API_Formats#Money|Money]]
| The total gross amount of the payment.
| 
|-valign="top"
| numberOfTickets
| [[REST_API_Formats#Integer|Integer]]
| The number of tickets associated with the payment.
| 
|-valign="top"
| paymentCurrency
| [[REST_API_Formats#Currency|Currency]]
| The Currency of the payment.
| 
|-valign="top"
| applicationData
| [[REST_API_Formats#String|String]]
| The application data passed through an integrated iframe. [[Payment_Application_Data|Click here for detailed information]]<br>
| 
|-valign="top"
| paymentFee
| [[REST_API_Formats#Money|Money]]
| The fee kept in by XING Events.
| 
|-valign="top"
| paymentShipmentFee
| [[REST_API_Formats#Money|Money]]
| The additional costs for shipment.
| 
|-valign="top"
| paymentSalesTax
| [[REST_API_Formats#Money|Money]]
| Sales tax included in the payment's gross amount (paymentValue).
| 
|-valign="top"
| paymentType
| [[REST_API_Payments#Payment_Type|PaymentType]]
| The payment type the buyer selected in this purchase.
| 
|-valign="top"
| paymentLanguage
| [[REST_API_Formats#Language|Language]]
| In which language did the buyer make his purchase.
| 
|-valign="top"
| paymentAffiliateFirstname
| [[REST_API_Formats#String|String]]
| First name of the affiliate who brought the buyer to the shop. Parameter is not send if no affiliate is associated to this purchase.
| 
|-valign="top"
| paymentAffiliateLastname
| [[REST_API_Formats#String|String]]
| Last name of the affiliate who brought the buyer to the shop. Parameter is not send if no affiliate is associated to this purchase.
| 
|-valign="top"
| paymentAffiliateEmail
| [[REST_API_Formats#String|String]]
| Email of the affiliate who brought the buyer to the shop. Parameter is not send if no affiliate is associated to this purchase.
| 
|-valign="top"
| paymentLoginType
| [[REST_API_Formats#String|String]]
| The "login with..." feature used by the buyer during buying process (if any). Possible values: "AMIANDO", "DOC_CHECK", "FACEBOOK", "XING"; 
| 
|-valign="top"
| paymentProfileId
| [[REST_API_Formats#String|String]]
| The profile ID of the buyer if he used a "Login with..." feature during the buying process.
| 
|-valign="top"
| paymentProfileUrl
| [[REST_API_Formats#String|String]]
| The profile URL of the buyer if he used a "Login with..." feature during the buying process.
| 
|-valign="top"
| distributionChannel
| [[REST_API_Formats#String|String]]
| The distributionChannel value indicated where the payment was made (e.g. Event page, XING, IFrame,...)
| 
|-valign="top"| 
| <b>Ticket parameters</b><br><br><br>
|
| (&lt;i>) stands for the number of the ticket. The first ticket will be ticketNumber0, the second one ticketNumber1 and so on. Note: if you buy tickets for a registration event, you will only get one instance of the parameter per purchase and no number will be appended to the parameter name (e.g. ticketNumber).
| 
|-valign="top"
| ticketNumber(&lt;i>)
| [[REST_API_Formats#String|String]]
| The public identifier (displayIdentifier) of the ticket. 
| 
|-valign="top"
| ticketIdentifier(&lt;i>)
| [[REST_API_Formats#String|String]]
| The identifier used in the barcode of the ticket.
| 
|-valign="top"
| participantId(&lt;i>)
| [[REST_API_Formats#Integer|Integer]]
| The internal id of the participant.
| 
|-valign="top"
| ticketId(&lt;i>)
| [[REST_API_Formats#Integer|Integer]]
| The internal id of the ticket.
| 
|-valign="top"
| ticketFirstName(&lt;i>)
| [[REST_API_Formats#String|String]]
| The first name associated with the ticket.
| 
|-valign="top"
| ticketLastName(&lt;i>)
| [[REST_API_Formats#String|String]]
| The last name associated with the ticket.
| 
|-valign="top"
| ticketEmail(&lt;i>)
| [[REST_API_Formats#String|String]]
| The email address associated with the ticket.
| 
|-valign="top"| 
| <b>Ticket category parameters</b><br><br>
|
| &lt;i> stands for the number of the ticket category. A ticketshop event has one ticket category per ticket (the ticketCategoryId0 is the ticket category of the ticket ticketId0). A ticket of a registration event can contain multiple ticket categories.
| 
|-valign="top"
| ticketCategory&lt;i>
| [[REST_API_Formats#String|String]]
| The name of the ticket category.
| 
|-valign="top"
| ticketCategoryId&lt;i>
| [[REST_API_Formats#Integer|Integer]]
| The internal id of the ticket category.
| 
|-valign="top"
| ticketCategoryPrice&lt;i>
| [[REST_API_Formats#Money|Money]]
| The original price of the ticket category.
| 
|}

==Conversion tracking sample==
This is an example on how you could implement a conversion tracking using the Tracking Webhook.<br/>
'''1.''' Create a new empty html page.
 <html>
 <head>
 </head>
 <body>
 </body>
 </html>
'''2.''' Now add the tracking code sniped you received from the system you want to integrate and place it between the <body> and </body> tags:
 <html>
 <head>
 [your tracking code here]
 </head>
 <body>
 </body>
 </html>
'''3.''' In case your tracking code needs to include dynamic information, e.g. the price of the purchase or the quantity of tickets bought, replace that placeholders with the values provided as POST parameters by the webhook. Otherwise continue with step 4.<br/>
'''4.''' Upload the html file to your server<br/>
'''5.''' Open the "Tracking" menu item in the administration area of your event and select "Browser call" as "Method of integration". In the address field enter the URL to the html page you uploaded to your server in step 4.<br/>

'''Done'''. Everytime now someone is buying a ticket in your event his browser will open your html file in the background (the user does not see the page) and the tracking code will be executed.

'''Sample for a conversion tracking for facebook advertisements:'''<br/>
The code provided by facebook to track the conversion of an advertisement may look like this:
 <!-- Facebook Pixel Code -->
 <script>
 !function(f,b,e,v,n,t,s){if(f.fbq)return;n=f.fbq=function(){n.callMethod?
 n.callMethod.apply(n,arguments):n.queue.push(arguments)};if(!f._fbq)f._fbq=n;
 n.push=n;n.loaded=!0;n.version='2.0';n.queue=[];t=b.createElement(e);t.async=!0;
 t.src=v;s=b.getElementsByTagName(e)[0];s.parentNode.insertBefore(t,s)}(window,
 document,'script','<nowiki>https://connect.facebook.net/en_US/fbevents.js</nowiki>');
 
 fbq('init', '[pixel_id]');
 fbq('track', "PageView");
 fbq('track', 'Purchase', {value: '[payment_amount]', currency:'[payment_currency]'});
 </script>
 <noscript><img height="1" width="1" style="display:none"
 src="<nowiki>https://www.facebook.com/tr?id=[pixel_id]&ev=PageView&noscript=1</nowiki>"
 /></noscript>
 <!-- End Facebook Pixel Code -->
This code contains multiple placeholder that need to be filled:<br/>
- '''[pixel_id]''': This is a number that references your facebook campaign and is provided by facebook (let's assume this is 1234)<br/>
- '''[payment_amount]''': Here facebook expects the price of the purchase, so this needs to be replaced dynamically with one of the webhook parameters.<br/>
- '''[payment_currency]''': Here facebook expects the currency of the purchase, so this needs to be replaced dynamically with one of the webhook parameters as well.<br/>
All three placeholders are used twice in the tracking code from facebook, therefor you have to replace every value twice.<br/>
- The amount of the purchase is provided by the webhook as a parameter with the name ''''paymentValue''''.<br/>
- The currency of the purchase is provided by the webhook as a parameter with the name ''''paymentCurrency''''.<br/>

How to use dynamic content in a HTML page on your server depends on the programming language installed on your system. As an example, this is how this would be done in PHP:
 [payment_amount] => "<?=$_POST['paymentValue']?>"
 [payment_currency] => "<?=$_POST['paymentCurrency']?>"
As the amount of the purchase is passed by our webhook in cent and facebook expects decimal amounts, we should divide the amount by 100, which can be done with PHP like this:
 <?=number_format($_POST['paymentValue']/100, 2, '.' , &apos;&apos; )?>
The full example would look like this:
 <html>
 <head>
 <!-- Facebook Pixel Code -->
 <script>
 !function(f,b,e,v,n,t,s){if(f.fbq)return;n=f.fbq=function(){n.callMethod?
 n.callMethod.apply(n,arguments):n.queue.push(arguments)};if(!f._fbq)f._fbq=n;
 n.push=n;n.loaded=!0;n.version='2.0';n.queue=[];t=b.createElement(e);t.async=!0;
 t.src=v;s=b.getElementsByTagName(e)[0];s.parentNode.insertBefore(t,s)}(window,
 document,'script','<nowiki>https://connect.facebook.net/en_US/fbevents.js</nowiki>');
 
 fbq('init', '1234');
 fbq('track', "PageView");
 fbq('track', 'Purchase', {value: '<?=number_format($_POST['paymentValue']/100, 2, '.' , &apos;&apos; )?>', currency:'<?=$_POST['paymentCurrency']?>'});
 </script>
 <noscript><img height="1" width="1" style="display:none"
 src="<nowiki>https://www.facebook.com/tr?id=1234&ev=PageView&noscript=1</nowiki>"
 /></noscript>
 <!-- End Facebook Pixel Code -->
 </head>
 <body>
 </body>
 </html>
As this is a PHP file, save it with the file extension .php, e.g. tracking.php and upload it to your server. Open the '''"Tracking"''' menu item in the administration area of your event and select '''"Browser-call"''' as '''"Method of integration"'''. In the address field enter the URL to the PHP page you uploaded to your server, e.g. <nowiki>https://www.my_website.com/tracking.php</nowiki>

==Perfect complement: Webhooks + XING TicketingManager REST API==
Get more info about the [[REST_API_Events|event]], the [[REST_API_Payments|payment]], the [[REST_API_Tickets|ticket]] (including user data) and the [[REST_API_TicketCategories|ticket categories]] via [[Event_Management_API|XING TicketingManager API]].