Callback Handling for Asynchronous Calls

When you submit an asynchronous request, you can configure the Options object to return the result as an HTTP POST callback or as an email. Alternatively, you can submit a Retrieve request to get ResultMessage objects and filter the results by the ResultID of the original request. To ensure that you receive responses quickly and reliably, we recommend that you configure asynchronous requests to return HTTP POST callbacks.

To use a callback to return results, set the value of the SendResponseTo.ResponseType property to HTTPPost. Next, specify a publicly accessible HTTPS URL for the value of the SendResponseTo.ResponseAddress property. The callback URL receives an HTTP POST request that uses the application/x-www-form-urlencoded content type and contains these fields.

  • RequestID
  • ConversationID
  • OverallStatusCode
  • StatusCode
  • StatusMessage
  • ErrorCode
  • RequestType
  • ResultType
  • ResultDetailXML
  • SequenceCode

If an HTTP POST callback results in an exception, the system logs an error and stops the process. Callbacks aren’t retried.

The callbacks that you receive correspond to the number of requests that you make. If you send 750 asynchronous SOAP requests, the system sends 750 POST requests to the callback URL. To reduce the number of callbacks, you can configure your requests to send multiple objects in a single call. You can also configure requests so that the system only sends callbacks when an error occurs.

If your request includes a RequestExpirationTime, add a SendResponseTo object that includes the RespondWhen.OnExpired property.