The ticketing tool "amiando" is now the "XING TicketingManager". With that re-branding we switched our domain from amiando.com to xing-events.com. Please update you API implementations to use the new domain. The API will be served on amiando.com until 01.05.2017

Tracking Webhooks

From XING Events Developer Documentation
Jump to: navigation, search

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 (Conversion tracking sample)
  • - saving ticket buyers' information into your own database
  • - 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 Integration tab. There are three integration methods:

  • No callback - The callback is disabled.
  • Browser call - 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 https://. Otherwise the user will see a 'Mixed-Content' error. This integration method is not as reliable as the server call.
  • Server call (recommended) - 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.

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):

Parameter
Type
Description

Event parameters
eventId Integer The internal database id of the event.
eventIdentifier String The public identifier of the event. The event page will be accessible at www.xing-events.com/<identifier>.html.
eventType String Whether the event is a registration-event (EVENT_TYPE_REGISTRATION) or a ticketshop-event (EVENT_TYPE_TICKETSHOP)
partnerIdentifier String The identifier of the partner.
Payment parameters
paymentId Integer The internal id of the payment.
paymentFirstName String First name of the ticket buyer
paymentLastName String Last name of the ticket buyer
paymentEmail String Email address of the ticket buyer
paymentTelephone String Telephone number of the ticket buyer (if provided)
paymentIdentifier String The invoice number of the payment. Will only be generated, if the total amount of the payment is greater than zero.
paymentDiscountCode String The discount/promotion code used for this purchase. If no discount code is used, this parameter will not be send.
paymentValue Money The total gross amount of the payment.
numberOfTickets Integer The number of tickets associated with the payment.
paymentCurrency Currency The Currency of the payment.
applicationData String The application data passed through an integrated iframe. Click here for detailed information
paymentFee Money The fee kept in by XING Events.
paymentShipmentFee Money The additional costs for shipment.
paymentSalesTax Money Sales tax included in the payment's gross amount (paymentValue).
paymentType PaymentType The payment type the buyer selected in this purchase.
paymentLanguage Language In which language did the buyer make his purchase.
paymentAffiliateFirstname 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.
paymentAffiliateLastname 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.
paymentAffiliateEmail String Email of the affiliate who brought the buyer to the shop. Parameter is not send if no affiliate is associated to this purchase.
paymentLoginType String The "login with..." feature used by the buyer during buying process (if any). Possible values: "AMIANDO", "DOC_CHECK", "FACEBOOK", "XING";
paymentProfileId String The profile ID of the buyer if he used a "Login with..." feature during the buying process.
paymentProfileUrl String The profile URL of the buyer if he used a "Login with..." feature during the buying process.
distributionChannel String The distributionChannel value indicated where the payment was made (e.g. Event page, XING, IFrame,...)
Ticket parameters


(<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).
ticketNumber(<i>) String The public identifier (displayIdentifier) of the ticket.
ticketIdentifier(<i>) String The identifier used in the barcode of the ticket.
participantId(<i>) Integer The internal id of the participant.
ticketId(<i>) Integer The internal id of the ticket.
ticketFirstName(<i>) String The first name associated with the ticket.
ticketLastName(<i>) String The last name associated with the ticket.
ticketEmail(<i>) String The email address associated with the ticket.
Ticket category parameters

<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.
ticketCategory<i> String The name of the ticket category.
ticketCategoryId<i> Integer The internal id of the ticket category.
ticketCategoryPrice<i> 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.
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.
4. Upload the html file to your server
5. Open the "Integration" tab in the administration area of your event and select "Webhook type: Browser". In the address field enter the URL to the html page you uploaded to your server in step 4.

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:
The code provided by facebook to track the conversion of an advertisement may look like this:

<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','https://connect.facebook.net/en_US/fbevents.js');

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="https://www.facebook.com/tr?id=[pixel_id]&ev=PageView&noscript=1"
/></noscript>

This code contains multiple placeholder that need to be filled:
- [pixel_id]: This is a number that references your facebook campaign and is provided by facebook (let's assume this is 1234)
- [payment_amount]: Here facebook expects the price of the purchase, so this needs to be replaced dynamically with one of the webhook parameters.
- [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.
All three placeholders are used twice in the tracking code from facebook, therefor you have to replace every value twice.
- The amount of the purchase is provided by the webhook as a parameter with the name 'paymentValue'.
- The currency of the purchase is provided by the webhook as a parameter with the name 'paymentCurrency'.

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, '.' , '' )?>

The full example would look like this:

<html>
<head>
<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','https://connect.facebook.net/en_US/fbevents.js');

fbq('init', '1234');
fbq('track', "PageView");
fbq('track', 'Purchase', {value: '<?=number_format($_POST['paymentValue']/100, 2, '.' , '' )?>', currency:'<?=$_POST['paymentCurrency']?>'});
</script>
<noscript><img height="1" width="1" style="display:none"
src="https://www.facebook.com/tr?id=1234&ev=PageView&noscript=1"
/></noscript>
</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 "Integration" tab in the administration area of your event and select "Webhook type: Browser". In the address field enter the URL to the PHP page you uploaded to your server, e.g. https://www.my_website.com/tracking.php

Perfect complement: Webhooks + XING TicketingManager REST API

Get more info about the event, the payment, the ticket (including user data) and the ticket categories via XING TicketingManager API.