Notification URLs and responses

When AppDirect sends an event notification, the vendor should first validate the request using the security method configured for the product. For more information, see Configure product integration security.

After validation, the vendor can use the eventUrl provided in the request to retrieve the full event details. Vendors may request the response in either JSON or XML:

• Use Accept: application/json to receive JSON
• Use Accept: application/xml to receive XML
• If no format is specified, AppDirect returns XML by default

After reviewing the event details, the vendor should process the requested action, such as creating, updating, or canceling an account.

Returning the result

Once processing is complete, the vendor should return a structured JSON or XML response indicating whether the operation succeeded or failed.

• Return HTTP 200 OK when processing has finished and the final result is being sent
• Set success to true if the operation completed successfully
• Set success to false if the operation could not be completed, and include an errorCode and message when possible
• Do not use generic HTTP error codes such as 500 or 404 to report business or provisioning failures

If the vendor is handling the event asynchronously, return HTTP 202 Accepted to indicate that processing is still in progress and provide the final result later through the supported completion flow. See Asynchronous subscription events for how to post the final result.

Success response to a notification

JSON

{
  "success": "true",
  "accountIdentifier": "new-account-identifier"
}

XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<result>
  <success>true</success>
  <accountidentifier>new-account-identifier</accountidentifier>
</result>

For Subscription Order events, include accountIdentifier so AppDirect can reference the customer account in future event notifications.

Error response to a notification

JSON

{
  "success": "false",
  "errorCode": "ACCOUNT_NOT_FOUND",
  "message": "The account TEST123 could not be found."
}

XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<result>
  <success>false</success>
  <errorcode>ACCOUNT_NOT_FOUND</errorcode>
  <message>The account TEST123 could not be found.</message>
</result>

Important

A vendor-reported failure tells AppDirect that the requested action could not be completed. In some cases, the event may still remain in a pending state temporarily depending on marketplace processing or recovery workflows.