Exitpoint Stage Documentation

prebid-server/developers/add-a-module-java.md

@@ -123,6 +123,7 @@ These are the available hooks that can be implemented in a module:
 - org.prebid.server.hooks.v1.bidder.RawBidderResponseHook
 - org.prebid.server.hooks.v1.bidder.AllProcessedBidResponsesHook
 - org.prebid.server.hooks.v1.auction.AuctionResponseHook
+- org.prebid.server.hooks.v1.exitpoint.ExitpointHook
 
 In a module it is not necessary to implement all mentioned interfaces but only one (or several) required by your functionality.
 
@@ -131,6 +132,17 @@ Each hook interface internally extends org.prebid.server.hooks.v1.Hook basic int
 - `code()` - returns module code.
 - `call(...)` - returns result of hook invocation.
 
+### Difference between AuctionResponseHook and ExitpointHook
+In a nutshell, both hooks allow the modification of the OpenRTB Bid Response but in different ways. 
+The `AuctionResponseHook` provides a last chance to work with the Java objects that modify the auction response.
+The `ExitpointHook` allows you to build a completely different response based on the received auction context. i.e. something that's not OpenRTB JSON - something like VAST. These hooks could modify the auction/amp/video response that PBS has built, or it could build another one and modify response headers accordingly.
+
+Important Notes:
+
+- The ExitpointHook is a powerful tool that allows rewriting the auction results, so make sure important data won't be lost for the client.
+- Since the response body is not modified after calling the ExitpointHook, debug and traces won't be added by PBS-core. The exitpoint hook is responsible for adding its own tracing to the generated output.
+- Analytics adapters doesn't have access to the response built by the ExitpointHook, but they receive the up-to-date auction context with the ExitpointHook execution status and analytics tags. 
+
 ### Examples
 
 1. To **update** the request in the `RawAuctionRequestHook` you would return:

prebid-server/developers/add-a-module.md

@@ -70,7 +70,8 @@ Here's a description of the Stages of a PBS request that modules can tap into fo
 | Bidder Request | The request has been customized for a particular bidder in the auction. Note that the module will be called in parallel for each bidder in the auction. | auction, amp, video | Bidder-specific bcat/badv, Bidder-specific deals |
 | Raw Bidder Response | Hook functions can get access to the unprocessed bidder response. Note that the module will be called in parallel for each bidder in the auction. | auction, amp, video | Response validations |
 | All Processed Bid Responses | All bids are back and PBS-core bid validations are done. | auction, amp, video | Creative validation, advanced bid validations. |
-| Auction Response | Last step before the response goes back to the client | auction, amp, video | Inject ad server targeting, alternate auction winner logic |
+| Auction Response | Last chance to modify the bid auction response | auction, amp, video | Inject ad server targeting, alternate auction winner logic |
+| Exitpoint | (PBS-Java 3.16+) Last step before the response goes back to the client. Specify the response headers and body | auction, amp, video | Create a VAST response instead of OpenRTB. |
 
 ### 3. Figure Out Which Stages You're Going to Hook Into