Using Webhooks

Predict.io supports delivering event notifications to your own servers as webhooks. Webhooks allow you to know that an event has happened and gives you the opportunity to perform some additional processing within your own API.

Why Webhooks?

Some examples of why you may want to receive webhooks would be to:

• Generate a notification sent to your app (we utilise this in our example projects)
• Capture a credit card payment at the end of a trip
• Send a location & journey based, time limited offer to a customer
• Validate a ticket or pass upon arrival at a destination

By not only relying on your mobile app to handle these events you can leverage the power within your existing API to perform any of these types of activities, and with the control being placed on the server side, you don't need to update your apps and can create additional use cases and enhanced customer engagement solely from the server side application.

Additionally, even less sensitive information has to reside on the customer's device allowing for a more tailored customer experience whilst utilising the security of your backend API.

Diagram explaining how webhooks can be used.

1. You call setCustomParameter() to set any custom data you want to receive, along with the event itself, on your API.
   • This may be data for push notification IDs, customer IDs, CSRF-esque tokens, etc.
   • To receive the webhook you must set the receiving URL with the setWebhookURL() in the SDK.
2. The predict.io SDK sends the event to the predict.io API and processes the request.
3. A webhook is generated and sent to the URL you set within setWebhookURL()
   • Here you can perform your custom business logic to determine what to do with the event
4. Optionally generate a notification from your API to your app.

---

Using Webhooks

1. Configure SDK

Follow the documentation for setting up the SDK for iOS, Android & Cordova.

After this you can setup support for webhooks by calling the setWebhookURL() method of the SDK, for example:

PredictIO.setWebhookURL("https://example.com/receive-webhook/here")

The SDK should now be configured to send all of the detected events onward to the URL which you define here.

2. Implement your API endpoint

To process the webhook, your API endpoint should be designed to receive only a POST HTTP verb and will come with the Content-Type & Accepts set to application/json and the payload will contain a JSON object on the route (documented later in this document).

3. Perform Trips

In order to validate your integration, as with the SDK itself, it's recommended that you perform some test trips where you can see the events being logged from the SDK. All events which are detected by the SDK will be forwarded to your webhook destination URL.

Event Types

Below is a list containing the possible events which can be received by using a webhook:

• departed
• transportation_mode
• searching_in_perimiter
• arrival_suspected
• departure_canceled
• arrived
• stationary

Full documentation on these events can be found on the iOS, Android or Cordova documentation.

Payload Structure

Example Payload Structure

{
  "event": {
    "event": "departed",
    "trip_segment_uuid": "980645d5-e713-4421-b4da-11ae852d03b3",
    "detected_at": "2016-10-24T14:59:34+00:00",
    
    "device": {
      "platform": "iOS",
      "platform_version": "10.0.2",
      "sdk_version": "i15.24.1"
      "vendor": "Apple",
      "model": "iPhone6,2"
    },

    "event_lat": "52.1",
    "event_lon": "8.04443",

    "transportation_mode": "car",
    
    "custom_data": {
      "device_token": "ABC123"
    }
  }
}

Device

device.platform can be identified as one of the values from the table below:

Value	Platform
iOS	Native iOS Application
Android	Native Android Application

Custom Data

This is a key/value string structure which can be used to transport additional data alongside events detected by the SDK. Values are set to here by using the setCustomParameter(key: String, value: String) method from the SDK.

Considerations

Authentication should be off on your webhook endpoint

When sending the POST of the webhook event, the request will not include any authentication; HTTP Basic, OAuth, or otherwise. Therefore you need to ensure that authentication is disabled for this endpoint in the case you are using some code to check that every request action is validate authenticated before being processed. Given that your API should be implemented over HTTPS, there is no additional security risk in disabling your authentication service, and it is recommended that you validate the events you receive.

Validate events your API receives

Following on from the notes on authentication above, you should use the details within the event payload to validate that the request is indeed genuine. This may be an additional ID which you set from the setCustomParameter() method within the SDK that you can then validate on the server side. Doing this will allow you to know that your received webhook is genuine.

Filter for events you want to process

All types of events generated by the SDK will be forwarded to your webhook destination URL automatically, it's up to the business logic on your API that you determine which event types you want to process.

Check you've set the webhook destination URL correctly

We've all done it ;) – there won't be any validation applied to the URL you supply, so please make sure it is completely correct. It's easy to become blind to a missing s in https, a mistyped domain or TLD or a wrongly placed /.

You'll experience this as no webhook being delivered, so if you want to confirm everything is working you should try using a RequestBin to ensure everything is working on the mobile side and use your server logs to determine what's happening on that end.