# Win Notification

* MediaMath delivers Win Notifications to the configured Custom Bid Router endpoints over HTTPS.
* The content type for the body of the request is set when the endpoint is configured. Therefore JSON (Content-Type: application/json) and Binary protobuf (Content-Type: application/protobuf) are supported.
* The Win Notification will be forwarded to the Custom Bid Router endpoints within seconds.
* Custom Bid Router does not implement a retry logic in case the Win Notification does not deliver successfully.
* Logging to S3 is currently not supported.
* Sample Rate is set to 100% (the full stream), but can be adjusted.


# Win Notification Protobuf definition

The Win Notification Protobuf definition can be found here:
[https://github.com/MediaMath/bid-valuator-endpoint-java/blob/master/src/main/proto/mediamath/winnotice/winnotice.proto](https://github.com/MediaMath/bid-valuator-endpoint-java/blob/master/src/main/proto/mediamath/winnotice/winnotice.proto)

# Setup Win Notification Endpoint

To setup a Win Notification Endpoint, follow the
[Win Notification Endpoint documentation](https://mediamath.stoplight.io/studio/api?source=qwIG522z3wELCDbfpjXA7&symbol=%252Fp%252Freference%252FBYOA.oas2.yml%252Fpaths%252F%7E1custombidrouter%7E1%257Borg_id%257D%7E1configuration%252Fget)

For every Win Notification Endpoint added, the endpoint_type field needs to be set to "win".

# Win Notification Sample Rate

The sample rate of an endpoint can be adjusted to selectively forward only a percentage of the Win Notifications. The sample rate can be adjusted collectively for all endpoints of an executor.


```bash
curl -X PATCH \
    https://api.byoa.mediamath.com/custombidrouter/{org_id}/executors/4 \
    -d '{"sample_rate": 75,
         "endpoint_type": "win"}' \
    -H 'authorization: Bearer <oauth_access_token>'
```

# Win Notification Example Request and Response

## Request

### Request Header

The X-Timeout header is set to 400ms. Which means that Custom Bid Router sets a deadline of 400ms for the win notification response to arrive. If it takes longer than 400ms, an error will be logged on the Grafana Dashboard.


```text
Content-Type: application/protobuf
X-Timeout: 400
```

### Request Body Example (protobuf decoded)

| Field | Description | Example |
|  --- | --- | --- |
| ExchangeAuctionID | Exchange Auction ID we receive | 8118261190986958665 |
| AuctionID | MM Auction ID unique to MM | 3023274093253060000 |
| BidPriceCpm | Bid price at CPM level in USD | 0.46974 |
| ClearPriceCpm | Amount SSP tells us the CPM cost once we have won auction | 0.469363 |
| TotalSpend | Total Spend CPM including all tracked fees | 0.899475 |
| MmUuid | Identifier for the user who received the ad | 93e75a86-036a-4000-9679-000000000000 |
| AdvertiserID | ID of the Advertiser in MediaMath for the campaign that won the impression | 123456 |
| CampaignID | Campaign ID for the impression win event | 123456 |
| StrategyID | ID for the impression win event at the granular strategy level | 123456 |
| CreativeID | Unique identifier that identifies the creative used in displaying the impression | 123456 |
| BidTimestamp | Converted to unix timestamp (note: will be at seconds and not milliseconds). In UTC time. | 2020-05-26 13:27:23 |


## Response

The Win Notification Response is expected to return the following Response back to Custom Bid Router.

### Response Header


```text
HTTP/1.1 200 OK
```

# Grafana Stats

* Win Notifications by Datacenter: shows the attempt Win Notification Requests
* Win Notification Responses by Datacenter: shows successful Win Notification Responses
* Win Notification Response Code Distribution: shows the Win Notification Response Code Distribution (expected 200)
* Win Notification Response Latency Distribution: shows the Win Notification Response Latency (max allowed 40ms)