Introduction

This section provides an overview of webhooks available in reserVie and how to use them. A webhook is a mechanism that allows reserVie to notify a server of something that has occurred in the system that that server might care about.

Subscribe to web hooks

Webhooks are current beta and so available on a limited basis and strictly on request. Please submit your use case via a support ticket and provide an endpoint.

Limitations of webhooks

reserVie serves webhooks after the event and in non-realtime. Typically this means that a webhook will be activated 1 - 2 minutes after the event. However, reserVie considers webhooks to be a low priority event and so this may take longer.

Requirements on end your application

The following requirements are placed on the application:

  • The application end point must be secured via HTTPS.

  • The application must accept webhook calls via a POST. All csrf protection must be disabled for these endpoints.

  • Upon receipt of the webhook, the application must respond immediately with a HTTP 200 OK response.

  • reserVie allows a maximum time of 2 seconds for the response to be received. If a timeout occurs, this will be treated as a failure.

  • reserVie allows up 10 failures after which webhooks will be automatically disabled.

  • Data is provided as JSON objects.

Securing webhooks

To ensure that you do detect fraudulent webhook invocations, we recommend that you validate all webhook calls using the private JWT key which is provided upon subscription. This token takes the form: XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX and is randomised and unique. The key is provided as part of the message.

If the key deviates from your private key, it is recommended that you disregard the message and return an appropriate HTTP response.

Webhook flow

reserVie expects the following flow:

simple webhook flow.png


webhooks

reserVie supports the following webhooks:

On Registration

The ‘on registration’ webhook is activated in response to a customer registering on reserVie. This is sent once only when the account is initially created.

Structure

{

version: 1,

type: ‘register’,

key: ‘xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx’,

time: ‘YYYY-MM-DD HH:mm:ss’,

data: {

customer: { firstname: '<first name>', lastname: '<last name>', 'email': '<email address>', mobile: '<string>, 'id': '<unique ID>'}

}

}

Detail:

version - this is the version of the API and associated data. You will be assigned a version on subscription and notified if updates are available.

type - this is the type of message. For ‘on registration’ type messages this will be set to ‘register’

key- Your private key

time - a date / time value of the ‘YEAR-MONTH-DAY HOUR:MINUTE:SECOND‘. All times are provided as 24 hour clock and based on UTC.

data - an object that contains sub objects with specific data relating to the event.

  • customer - an object which contains the customers details

    • firstname - the first name of the client

    • lastname - the last name of the client

    • email - the email address of the client

    • id: a unique ID associated to the client and email. This can be used as a foreign key in your database look up.

On Purchase

The ‘on purchase’ webhook is activated in response to a customer a purchase is made. There are two types of ‘on purchase webhooks:

  1. Pass purchase

  2. Event purchase

Structure of pass purchase

{

version: 1,

type: ‘purchase’,

key: ‘xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx’,

time: ‘YYYY-MM-DD HH:mm:ss’,

data: {

type: ‘customer-pass’,

customer: '<unique ID>',

purchase: { parent_id: <integer>, pass: {id: <integer>, expires: ‘YYYY-MM-DD‘, credits: <integer> } }

}

}

Detail:

version - this is the version of the API and associated data. You will be assigned a version on subscription and notified if updates are available.

type - this is the type of message. For ‘on purchase’ type messages this will be set to ‘purchase’

key- Your private key

time - a date / time value of the ‘YEAR-MONTH-DAY HOUR:MINUTE:SECOND‘. All times are provided as 24 hour clock and based on UTC.

data - an object that contains sub objects with specific data relating to the event.

  • type - what has been purchased. event or pass

  • customer - ID associated to the registered customer

  • purchase - an object which contains details of the purchase

    • parent_id - the ID of the pass that has been purchased.

    • pass - Object containing:

      • id - the ‘customer-pass’ id.

      • expires - the expiry of the pass

      • credits - the number of credits purchased.

Structure of pass purchase

{

version: 1,

type: ‘purchase’,

key: ‘xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx’,

time: ‘YYYY-MM-DD HH:mm:ss’,

data: {

type: ‘event’,

customer: '<unique ID>',

purchase: { eid: <integer>, dateid:<integer>, transactionid:<integer>, pricingoption: <integer> }

}

}

Detail:

version - this is the version of the API and associated data. You will be assigned a version on subscription and notified if updates are available.

type - this is the type of message. For ‘on purchase’ type messages this will be set to ‘purchase’

key- Your private key

time - a date / time value of the ‘YEAR-MONTH-DAY HOUR:MINUTE:SECOND‘. All times are provided as 24 hour clock and based on UTC.

data - an object that contains sub objects with specific data relating to the event.

  • type - what has been purchased. event or pass

  • customer - ID associated to the registered customer

  • purchase - an object which contains details of the purchase

    • eid - the ID of the event

    • dateid - the date object id.

    • transaction - the transaction id associated to the purchase

    • pricingoption - the id of the pricing option purchased.