How Product Lifecycle API works
About Product Lifecycle API
Product Lifecycle API communicates product Lifecycle information between the marketplace and partners. Partners receive notification messages over HTTPS through a configured webhook.
Example notification flow for a new purchase
- Implement Product Lifecycle API. To get started, refer to Subscription management service.
- Endpoint URL and credentials are registered.
- Entitlement operations:
- subscribe
- unsubscribe
- update
- Suspend
- resume
- Product Lifecycle API notifications
- subscribe
- unsubscribe
- update
- Suspend
- resume
Product onboarding and Product Lifecycle API
During onboarding, for each product, partners configure Subscription management service, which automatically notifies partners on customer events associated with their products. To receive event notifications using Product Lifecycle API, on Partner portal, partners need to provide a webhook URL. For more information, refer to Subscription management service.
Receiving notifications through webhooks
All event notifications will be a PUT in the context of a unique event
identifier and will follow a common structure. The webhooks are expected to be
idempotent in processing the events and any duplicate notifications for the same
eventId should be handled gracefully.
Event notifications have a common structure that includes a wrapper with a nested data object. The data object includes specific information on the event type action, subscription plan, product edition, customer details, and more.
Changes and version control for Product Lifecycle API
Product Lifecycle API adheres to the following change policy for minor versions:
- Existing endpoints and fields MUST NOT be removed or renamed.
- New OPTIONAL endpoints, or new HTTP methods for existing endpoints, MAY be added to enable support for new features.
- New fields MAY be added to existing request/response messages. These fields MUST be OPTIONAL and SHOULD be ignored by clients and servers that do not understand them.
Changes since latest release
- Initial Version - No changes being documented
Authentication
All communication will be over HTTPS with a self-signed certificate. All
messages are authenticated using basic authentication. When authentication
fails, partners must respond with 401 Unauthorized.
Responding to notifications
After receiving an event notification, the webhook should respond consistent with standard HTTP codes with a message where ever applicable for error scenarios.
| HTTP Code | Platform Action | Description |
|---|---|---|
| 200 | Accepted | The webhook should always return a 200 if the event was successfully accepted irrespective of the status of event processing. The platform marks the operation as complete or retries until the operation is marked complete or failed. If the status is failed there MUST be a message describing the failure and will trigger a manual intervention |
| 404 | Retries | The registered endpoint was unreachable and the platform retries the event, until the retries run out which would force a manual intervention. |
| 4xx | Manual Intervention | The platform assumes that there is either a configuration issue (authentication/authorization errors) or an issue with the input and triggers a manual flow. |
| 5xx | Retries | The registered endpoint was unreachable and the platform retries the event, until the retries run out which would force a manual intervention. |
Retries
For all HTTP message failures, Red Hat Marketplace retries sending the request
message until we receive a 200 Success response message. Retry intervals begin
at two seconds decaying exponentially to a max delay of four hours after which
the system retries every four hours.
When the marketplace receives a 200 Success response and the status is
inprogress or needs_user_input we retry the request every five minutes or
after the specified retryAfter interval until the status changes to complete
or failed.
Manual Intervention
Under certain circumstances, when the marketplace can’t automatically retry, we will send partners an email message with the event notification information.
Sync vs Async
All events can be processed either synchronously or asynchronously and the
webhook can use the 200 Success response with the status codes and retries
described on API reference. When event
processing exceeds 20 seconds, partners should process the event asynchronously.
Using the Callback URL to respond
While Red Hat Marketplace retires the request, partners might want to update the status or mark an operation as complete between the retries (as soon as they have completed it) and they can use the callback URL to do that. You can send the same response body that you were required to send for the event to the callback URL to achieve this.
Event type: Subscribe
Partners subscribing to subscription events, receive up to five action types corresponding with a product Lifecycle event:
- new subscription, either trial or paid
- updated subscription
- suspended or resumed subscription
- cancel subscription
Event notifications include the following supporting information:
- customer details
- product edition details
- event details
Subscribe
This event is sent when a customer purchases or trials a product that the webhook has been registered for. The event has all the details required to help provision the product for the customer. For more information, refer to New or updated subscription.
Update
This message indicates a change in subscription parameters. An example of a change could be from trial to a purchased subscription where an editionId will also change. The message will carry the complete set of properties for the updated subscription. For more information, refer to New or updated subscription.
Unsubscribe
The unsubscribe message is sent to the webhook to indicate that the subscription has been removed and the Product Controller needs to take the appropriate clean up actions. For more information, refer to Suspended, resumed, or unsubscribed subscription.
Suspend
The suspend message is sent to the webhook to indicate that the subscription has been moved to a suspended state. It should be moved to an unusable but provisioned state. Any resources and data associated with it typically remain and are not destroyed. At some point in the future it may be resumed for use. For more information, refer to Suspended, resumed, or unsubscribed subscription.
Resume
The resume message is sent to the webhook to indicate that a suspended subscription must be reactivated and made accessible and usable to the customer. For more information, refer to Suspended, resumed, or unsubscribed subscription.
Product Lifecycle API reference
For details on methods, endpoints, requests, and responses, refer to Product Lifecycle API reference.