API Event Overview

Last Edited: July 5th, 2012

You need to implement a few APIs and URL endpoints in order to integrate with AppDirect. The AppDirect "Event Engine" covers most of the AppDirect integration requirements. We define Events as actions that customer administrators take in AppDirect that affect the status of their account or subscription with an Application Vendor. Example Events might include buying subscriptions, upgrading subscriptions, or deleting accounts. When an event occurs, AppDirect will notify you by calling a specific URL hosted by you and passing as a parameter a URL that you'll be using to fetch information about this Event.

Event Types

Application Vendors must register "Event Listener" URLs (secured with OAuth) with AppDirect that will receive Event URLs. You can implement a URL for each Event type or use a single URL to handle all of them. The following events are currently supported by AppDirect:

SUBSCRIPTION_ORDER: fired by AppDirect when a user buys an app from AppDirect.
SUBSCRIPTION_CHANGE: fired by AppDirect when a user upgrades/downgrades/modifies an existing subscription.
SUBSCRIPTION_CANCEL: fired by AppDirect when a user cancels a subscription.
SUBSCRIPTION_NOTICE: fired by AppDirect when a subscription goes overdue or delinquent.
USER_ASSIGNMENT: fired by AppDirect when a user assigns a user to an app.
USER_UNASSIGNMENT: fired by AppDirect when a user unassigns a user from an app.

Endpoint URLs

Applications must register Endpoint URLs to handle these events and other integrations. See the Account Subscription API documentation and the Access Management API documentation for more details.

We highly recommend that developers use HTTPS endpoints secured with SSL certificates. Such certificates have to be valid and verifiable by the AppDirect server for the integration to work. In order for the integration to work if a certificate does not pass this validation, it should either be fixed by the developer integrating his or her app, or manually added to the AppDirect server list of trusted certificates (using the Java keytool utility).

AppDirect's REST Event API

As mentioned, AppDirect will notify you of an Event by passing a URL. This URL will point at the Event REST API for the AppDirect-powered marketplace the Event has taken place on. Upon notification, you can perform an HTTP GET to that URL to read an XML representation of that Event.

This URL will look like https://www.appdirect.com/api/integration/v1/events/${token} for Events taking place on the AppDirect marketplace, or https://businessapps.bell.ca/api/integration/v1/events/${token} for Events taking place on a different marketplace (Bell Business Apps Store, etc).

You need to sign calls to this API using "2-legged OAuth" also known as "signed fetch." For more information, please read the OAuth API Authorization document.

Sample hard coded data showing the XML structure can be found at these locations: