Webhooks: Integrating with events generated by YouLi - Payments and Tasks

Do you have another system, like an email platform, CRM or even Slack, that needs to be kept in sync with YouLi? Then you need webhooks!

Background

If you need the technical details about how to subscribe to webhooks:

See API specification here

Not a developer?

Do you want automation without the code? Check out our Zapier documentation

Data Included in Webhook JSON Objects

See samples below for more details.

Meta-data for the invitee (traveler)
- Including the "Id" that can be used to identify them uniquely - always provided
- if provided: includes the email address
- "ResponseDietaryRequirement" is a DEPRECATED field - IGNORE
Number in Group (if greater than 1 they are in an invitation group)
Standard Trip data
Package, Room and Price data
Special data relating to the type of webhook (see below)
- Payments include a Payment and Allocation object AND any previously completed Task Responses
- Task Responses include a task Response object that varies based on the response type

WARNING: Email address is NOT required in the YouLi platform if the invitee is added by the planner or they have been added as a member of an invitation group, so this may be missing and that case must be handled if you need that to lookup in an external system

Payments Trigger

Below is an example of the JSON provided to the webhook when subscribed to

Payments for just one of your Trips (special handling on per trip basis)

or
All of your Trips (most common use case)

Payment Status

Check this value to determine how to handle the payment

successful
refunded
sent
- These are triggered by the payments methods that require manual confirmation before they become successful
- Best to treat these as pending - you may choose to ignore them and simply wait for the successful event once confirmed the payment has arrived

TIP: Previously completed Task Responses are included in the Payment JSON since it might include information you need to lookup/update - especially the Custom Profile & Registration Task

{
  "Id": "6725ecd7-6491-ed11-bf7a-14cb653278d6",
  "FullName": "oh happy day",
  "FirstName": "oh",
  "LastName": "happy day",
  "Email": "whatahappyday@gmail.com",
  "PhoneNumber": "04123456789",
  "BillToFirstName": null,
  "BillToLastName": null,
  "BillToStreetLine1": null,
  "BillToStreetLine2": null,
  "BillToCity": null,
  "BillToCountry": null,
  "BillToState": null,
  "BillToPostCode": null,
  "AvatarURL": "https://ylt-images.imgix.net/app/invitees-icon@2x.png?fit=crop&crop=faces&h=150&w=150",
  "MiniBio": null,
  "RegistrationStatus": 1,
  "RegistrationDateReceivedUTC": "2023-01-11T04:03:03.2",
  "RegistrationNote": null,
  "ResponseDietaryRequirement": null,
  "PlannerNote": null,
  "InvitationGroup": "",
  "InvitationGroupMembers": [
    {
      "FullName": "oh happy day",
      "FirstName": "oh",
      "LastName": "happy day",
      "Email": "whatahappyday@gmail.com"
    }
  ],
  "NumberInGroup": 1,
  "ReferenceCode": "GKMAZDO3JN",
  "PackageName": "Single",
  "PackageCode": null,
  "PackageFeesAndTaxesAmount": 0,
  "BasePrice": 10,
  "Room": null,
  "AmountOwing": 108,
  "TripId": "ca20e7ca-bd6e-ed11-ade6-14cb65328659",
  "TripName": "select usd",
  "TripAlias": "select-test-trip-1-1-2-1-1-1",
  "TripRegistrationButtonLabel": "Express interest",
  "TripTags": null,
  "TripStartDateUTC": "2023-12-19T13:00:00Z",
  "TripEndDateUTC": "2023-12-19T13:00:00Z",
  "MagicLink": "https://youli.io/t/youli-checkout-flow/test-trip/xxxxx3",
  "TrackingSource": "facebook.com",
  "TrackingMedium": "referral",
  "TrackingCampaign": "summer-promo",
  "Payment": {
    "Id": "ef57c268-6591-ed11-bf7a-14cb653278d6",
    "Amount": 13.2,
    "Currency": "USD",
    "Method": "stripe",
    "Description": "GKMAZDO3JN : oh happy day : select usd : Deposit : 1 person",
    "Status": "successful",
    "PaymentDateUTC": "2023-01-11T04:07:14.887",
    "YouLiFeeAmount": 0.18,
    "YouLiFeeCurrency": "AUD",
    "CreditCardSurchargeAmount": 1.2,
    "CreditCardSurchargeCurrency": "USD",
    "RefundProtectSurchargeAmount": 0,
    "RefundProtectSurchargeCurrency": "USD",
    "GatewayFee": 0.76,
    "GatewayFeeTax": 0.08,
    "GatewayFeeCurrencyCode": "AUD",
    "GatewayFeeTaxDescription": "GST",
    "Allocations": [
      {
        "Id": "6725ecd7-6491-ed11-bf7a-14cb653278d6",
        "FullName": "oh happy day",
        "FirstName": "oh",
        "LastName": "happy day",
        "Amount": 12,
        "Installment": "Deposit"
      }
    ]
  },
  "TaskResponses": [
    {
      "Id": "6a25ecd7-6491-ed11-bf7a-14cb653278d6",
      "TaskId": "f19d3b38-0077-ed11-ade6-14cb65328659",
      "TaskName": "Profile",
      "TaskResponseType": 10,
      "ResponseValue": "",
      "HasFields": true,
      "FieldResponses": [
        {
          "APIFieldName": "FIRST_NAME",
          "FieldLabel": "First name",
          "FieldResponseValue": "oh"
        },
        {
          "APIFieldName": "LAST_NAME",
          "FieldLabel": "Last name",
          "FieldResponseValue": "happy day"
        },
        {
          "APIFieldName": "EMAIL",
          "FieldLabel": "Email",
          "FieldResponseValue": "whatahappyday@gmail.com"
        },
        {
          "APIFieldName": "PHONE_NUMBER",
          "FieldLabel": "Phone number",
          "FieldResponseValue": "04123456789"
        },
        {
          "APIFieldName": "UPLOAD_AVATAR",
          "FieldLabel": "Upload Avatar",
          "FieldResponseValue": "Not provided"
        },
        {
          "APIFieldName": "DATE_OF_BIRTH",
          "FieldLabel": "Date of Birth",
          "FieldResponseValue": "Not provided"
        },
        {
          "APIFieldName": "MINI_BIO",
          "FieldLabel": "Mini Bio",
          "FieldResponseValue": null
        },
        {
          "APIFieldName": "123123123",
          "FieldLabel": "upload avatar no api",
          "FieldResponseValue": ""
        },
        {
          "APIFieldName": null,
          "FieldLabel": "check box",
          "FieldResponseValue": ""
        },
        {
          "APIFieldName": null,
          "FieldLabel": "select country",
          "FieldResponseValue": ""
        },
        {
          "APIFieldName": null,
          "FieldLabel": "multi line",
          "FieldResponseValue": ""
        }
      ]
    },
    {
      "Id": "cb780704-6591-ed11-bf7a-14cb653278d6",
      "TaskId": "0821e7ca-bd6e-ed11-ade6-14cb65328659",
      "TaskName": "Passport",
      "TaskResponseType": 8,
      "ResponseValue": "",
      "HasFields": true,
      "FieldResponses": [
        {
          "APIFieldName": "passport_issue_date",
          "FieldLabel": "passport issue date",
          "FieldResponseValue": "11 Jan 2017"
        },
        {
          "APIFieldName": "passport_expiration_date",
          "FieldLabel": "Passport Expiration Date",
          "FieldResponseValue": "11 Jan 2027"
        },
        {
          "APIFieldName": null,
          "FieldLabel": "confirm your name",
          "FieldResponseValue": "oh happy day"
        }
      ]
    },
    {
      "Id": "91235020-6591-ed11-bf7a-14cb653278d6",
      "TaskId": "0621e7ca-bd6e-ed11-ade6-14cb65328659",
      "TaskName": "Download the Mobile App",
      "TaskResponseType": 1,
      "ResponseValue": "Done",
      "HasFields": false,
      "FieldResponses": []
    }
  ]
}

WARNING: If you need to know which Installment was paid, check the Allocations (one level down from the payment level).

If it is a catch-up payment (many Installments) then no Installment value will be provided.

Task Response Trigger

Example of a the JSON provided to the webhook when subscribed to

Tasks for one of your Trips (special handling on per trip basis)

or
All of your Trips (most common use case)

SAMPLE: Custom Form Response Example (Response Type 8)

{
  "Id": "6725ecd7-6491-ed11-bf7a-14cb653278d6",
  "FullName": "oh happy day",
  "FirstName": "oh",
  "LastName": "happy day",
  "Email": "whatahappyday@gmail.com",
  "PhoneNumber": "04123456789",
  "BillToFirstName": null,
  "BillToLastName": null,
  "BillToStreetLine1": null,
  "BillToStreetLine2": null,
  "BillToCity": null,
  "BillToCountry": null,
  "BillToState": null,
  "BillToPostCode": null,
  "AvatarURL": "https://ylt-images.imgix.net/app/invitees-icon@2x.png?fit=crop&crop=faces&h=150&w=150",
  "MiniBio": null,
  "RegistrationStatus": 1,
  "RegistrationDateReceivedUTC": "2023-01-11T04:03:03.2",
  "RegistrationNote": null,
  "ResponseDietaryRequirement": null,
  "PlannerNote": null,
  "InvitationGroup": "",
  "InvitationGroupMembers": [
    {
      "FullName": "oh happy day",
      "FirstName": "oh",
      "LastName": "happy day",
      "Email": "whatahappyday@gmail.com"
    }
  ],
  "NumberInGroup": 1,
  "ReferenceCode": "GKMAZDO3JN",
  "PackageName": "Single",
  "PackageCode": null,
  "PackageFeesAndTaxesAmount": 0,
  "BasePrice": 1000,
  "Room": null,
  "AmountOwing": 500,
  "TripId": "ca20e7ca-bd6e-ed11-ade6-14cb65328659",
  "TripName": "select usd",
  "TripAlias": "select-test-trip-1-1-2-1-1-1",
  "TripRegistrationButtonLabel": "Express interest",
  "TripTags": [],
  "TripStartDateUTC": "2023-12-19T13:00:00Z",
  "TripEndDateUTC": "2023-12-19T13:00:00Z",
  "MagicLink": "https://youli.io/t/youli-checkout-flow/select-test-trip-1-1-2-1-1-1/xxxxxxx",
  "TrackingSource": "unknown",
  "TrackingMedium": "referral",
  "TrackingCampaign": "",
  "TaskResponse": {
    "Id": "cb780704-6591-ed11-bf7a-14cb653278d6",
    "TaskId": "0821e7ca-bd6e-ed11-ade6-14cb65328659",
    "TaskName": "Passport",
    "TaskResponseType": 8,
    "ResponseValue": "",
    "HasFields": true,
    "FieldResponses": [
      {
        "APIFieldName": "passport_issue_date",
        "FieldLabel": "passport issue date",
        "FieldResponseValue": "11 Jan 2017"
      },
      {
        "APIFieldName": "passport_expiration_date",
        "FieldLabel": "Passport Expiration Date",
        "FieldResponseValue": "11 Jan 2027"
      },
      {
        "APIFieldName": null,
        "FieldLabel": "confirm your name",
        "FieldResponseValue": "oh happy day"
      }
    ]
  }
}

SAMPLE: Standard "Done" Task Response (Response Type 1)

{
  "Id": "6725ecd7-6491-ed11-bf7a-14cb653278d6",
  "FullName": "oh happy day",
  "FirstName": "oh",
  "LastName": "happy day",
  "Email": "whatahappyday@gmail.com",
  "PhoneNumber": "04123456789",
  "BillToFirstName": null,
  "BillToLastName": null,
  "BillToStreetLine1": null,
  "BillToStreetLine2": null,
  "BillToCity": null,
  "BillToCountry": null,
  "BillToState": null,
  "BillToPostCode": null,
  "AvatarURL": "https://ylt-images.imgix.net/app/invitees-icon@2x.png?fit=crop&crop=faces&h=150&w=150",
  "MiniBio": null,
  "RegistrationStatus": 1,
  "RegistrationDateReceivedUTC": "2023-01-11T04:03:03.2",
  "RegistrationNote": null,
  "ResponseDietaryRequirement": null,
  "PlannerNote": null,
  "InvitationGroup": "",
  "InvitationGroupMembers": [
    {
      "FullName": "oh happy day",
      "FirstName": "oh",
      "LastName": "happy day",
      "Email": "whatahappyday@gmail.com"
    }
  ],
  "NumberInGroup": 1,
  "ReferenceCode": "GKMAZDO3JN",
  "PackageName": "Single",
  "PackageCode": null,
  "PackageFeesAndTaxesAmount": 0,
  "BasePrice": 10,
  "Room": null,
  "AmountOwing": 120,
  "TripId": "ca20e7ca-bd6e-ed11-ade6-14cb65328659",
  "TripName": "select usd",
  "TripAlias": "select-test-trip-1-1-2-1-1-1",
  "TripRegistrationButtonLabel": "Express interest",
  "TripTags": [],
  "TripStartDateUTC": "2023-12-19T13:00:00Z",
  "TripEndDateUTC": "2023-12-19T13:00:00Z",
  "MagicLink": "https://youli.io/t/youli-checkout-flow/select-test-trip-1-1-2-1-1-1/xxxxxx",
  "TrackingSource": "unknown",
  "TrackingMedium": "referral",
  "TrackingCampaign": "",
  "TaskResponse": {
    "Id": "91235020-6591-ed11-bf7a-14cb653278d6",
    "TaskId": "0621e7ca-bd6e-ed11-ade6-14cb65328659",
    "TaskName": "Download the Mobile App",
    "TaskResponseType": 1,
    "ResponseValue": "Done",
    "HasFields": false,
    "FieldResponses": []
  }
}

Need more help?

For more tips on pre-trip customer support join the YouLi community of travel professionals with monthly LIVE webinars and Q&A sessions.