Setting Up Your Event Subscription Endpoint

Standard Event Subscription Message Delivery Requirements

Your configured service endpoint, which consumes Workfront event subscription messages, must meet the following requirements:

  • The service endpoint must accept HTTP POST requests.
    HTTP POST is the request method used in all deliveries of event subscription messages, including validation messages.
  • In order for the event subscription delivery system to acknowledge the message was successfully received, the endpoint must return a 200-level HTTP status (for example, 200 OK or 202) for all incoming messages.
    If a 200-level status is not returned, the event subscription system assumes the message was not delivered successfully and begins applying the appropriate retry policy. To learn more about the Workfront retry policy, see "Understanding Event Subscription Retries."
  • In conjunction with returning a 200-level status as the response status, the HTTP response must be received within five seconds after the delivery attempt started.
    The purpose of this constraint is to ensure that consumer business processes or infrastructure limitations do not delay the delivery of other messages pending delivery.
    If you have a long-running business process that triggers from an event subscription message, Workfront recommends that your endpoint save the message information upon receipt via any available medium and then immediately responds with a 200-level status. After your endpoint has responded to the event subscription message delivery request, you can then process the saved messages.

Event Subscription Message Delivery

Workfront supports the following types of event subscription messages:

  • Standard Message: Sent automatically from Workfront after you have correctly configured your service and created an Event Subscription to trigger those message deliveries.
  • Validation or Test Message: Evaluates and reports on whether the following conditions are met: 
    • Your configured service endpoint is available and ready to receive messages.
      If your endpoint is not ready when outbound messages are sent, then the thousands of messages sent by Workfront have no possibility of being successfully received in near real time.
    • There are secure means through which messages can be routed to their appropriate destinations.
      Before sending live messages which could contain sensitive information, the validation message ensures messages can be securely sent.

Your endpoint should be able to differentiate between a standard message and a validation message. A key difference between the two types of messages is that the eventType attribute for a validation message is always VALIDATE, while standard messages always contain their corresponding eventType, such as CREATE, UPDATE, and DELETE. In addition, the subscriptionID attribute in validation messages contains a random alphanumeric value, which the consuming service pulls out of the request and places into the X-Workfront-Eventsub-Confirmation header of the response. It is this exchange of the random alphanumeric value that verifies the message is being routed to the right place. 


This article last updated on 2018-09-12 22:53:23 UTC