Validate outbound event notifications

Outbound event notifications are webhook notifications that AppDirect sends to your registered integration endpoints when an action is performed on an AppDirect marketplace (for example, when a subscription is purchased for your product).

You configure your integration endpoints when you configure your product. See Edit integration.

When you configure the Separate Credentials authorization type, you can select OAuth 2.0 or Basic authentication. See Manage credentials for more information.

OAuth 2.0 authentication

If you select OAauth 2.0 for outbound notifications, AppDirect retrieves an OAuth 2.0 access token from your configured token endpoint using the client credentials grant type. AppDirect includes this token in the Authorization header of all event notifications.

Authorization: Bearer <access_token>

See the OAuth 2.0 Authorization Framework specification for information about this grant type.

📝 Note If you configure outbound notifications to use basic authentication, inbound authentications always use OAuth 2.0 authentication. Additionally, the username and password are included in the Authentication header for all event notifications and can be easily decoded by anyone who could intercept those events. Because of this, basic authentication should always be used in combination with other security mechanisms such as HTTP (SSL).

The following image illustrates this flow.

1. An event is triggered by a customer action (for example, an application purchase).
2. The AppDirect marketplace initiates authorization with a POST request to the configured token endpoint to exchange the registered client’s credentials for an access token. This request is authenticated (basic authentication) using the client ID and secret.

Sample request:

curl -X POST -u appdirect-49:9vY0s4yb2pbnP7Vz -H 'Content-Type: application/x-www-form-urlencoded' "https://www.isv.com/oauth2/token" -d "grant_type=client_credentials&scope=post_subscription_events"  

Parameter	Description
grant_type	Must be client_credentials, which indicates that this is the Client Credentials grant type.
scope	A space-separated list of requested scopes. The list of scopes is configured within the Credentials section of your product profile.

3. The access token is returned to the AppDirect marketplace.
   Sample response:

"access_token": "7iVGxe84f1ew6QENpCD3...",  
"token_type": "bearer",  
"expires_in": 43199,  
"scope": "post_subscription_events"  

4. AppDirect sends a subscription event notification to your registered endpoint and includes the access token in the Authorization header as a bearer token.

Sample:

curl -X GET -H 'Authorization: Bearer 7iVGxe84f1ew6QENpCD3...' "http://example.com/create?url=https://www.acme-marketplace.com/api/integration/v1/events/12345"

5. Your application validates the access token sent in the Authorization header of the subscription event notification.
6. Your application returns a JSON or XML response to the event notification that indicates the status of the event.
7. A confirmation is returned to the end user.

Basic authentication

If you select basic authentication for outbound notifications, AppDirect includes the registered username and password in the Authorization header of all event notifications.

Sample header:

Authorization: Basic <credentials>

The credentials parameter is a base64 encoded string username:password (the registered username, followed by a colon, followed by the registered password).

Sample:

Authorization: Basic c3VwZXJoZXJvOmhlcm9lczlwMjBA>

📝 Note The value included in the Authorization header can be easily decoded by anyone who can intercept the event notification. Because of this, basic authentication should always be used in combination with other security mechanisms such as HTTPS (SSL).

The following image illustrates this flow:

1. An event is triggered by a customer action (for example, an application purchase).
2. AppDirect sends a subscription order event notification to your registered endpoint and includes the base64 encoded username and password in the Authorization header.

Example:

curl -X GET -u exampleuser:p@ssw0rd "http://example.com/create?url=https://www.acme-marketplace.com/api/integration/v1/events/12345"

3. Your application validates the basic authentication username and password sent in the Authorization header of the subscription event notification.

📝 NoteThe username and password are included in the Authentication header for all event notifications and can be easily decoded by anyone who could intercept those events. Because of this, basic authentication should always be used on combination with other security mechanisms such as HTTP (SSL).

4. Your application returns a JSON or XML response to the event notification that indicates the status of the event.
5. A confirmation is returned to the end user.