# Ratings and Webhooks

## Initial Rating Retrieval

When a user first connects, you can retrieve their initial rating directly from the [SSO Login](/dupr-raas/integration-checklist/sso-login.md) response.

***

## Updating Ratings via Webhooks

Rating updates are pushed to a custom URL provided by your application. This process involves two steps: registering your webhook and subscribing individual users.

#### Step 1: Setting up the Webhook

Before you can receive updates, you must register your endpoint.

<table><thead><tr><th width="186">Environment</th><th>API</th></tr></thead><tbody><tr><td>UAT</td><td><a href="https://uat.mydupr.com/api/swagger-ui/index.html#/ApiRegistration/register">UAT: Register Webhook URL</a></td></tr><tr><td>Production</td><td><a href="https://prod.mydupr.com/api/swagger-ui/index.html#/ApiRegistration/register">Prod: Register Webhook URL</a></td></tr></tbody></table>

**Example Request Body:**

```json
{
  "webhookUrl": "https://www.partner-webhook-url.com/webhook",
  "topics": [
    "RATING"
  ]
}
```

The `clientId` is derived from the `Authorization: Bearer <partner token>` header — do not include it in the request body.

{% hint style="info" %}
**Security:** The URL must use HTTPS with a valid, verifiable certificate (no self-signed certificates).

**Responsiveness:** Your endpoint must return a `200 OK` status for both test and real messages within a few seconds

**Pathing:** Provide the full path that will resolve the request (e.g., `https://domain.com/webhook`).
{% endhint %}

#### Step 2: Subscribing Users

Once your webhook is registered, you must subscribe every user in your system to receive their specific rating updates.

<table><thead><tr><th width="186">Environment</th><th>API</th></tr></thead><tbody><tr><td>UAT</td><td><a href="https://uat.mydupr.com/api/swagger-ui/index.html#/Users/subscribeUserWebhookEvent">UAT: Subscribe to User Webhook Event</a></td></tr><tr><td>Production</td><td><a href="https://prod.mydupr.com/api/swagger-ui/index.html#/Users/subscribeUserWebhookEvent">Prod: Subscribe to User Webhook Event</a></td></tr></tbody></table>

Example request body:

```json
{
  "duprIds": ["1A1A1A"],
  "topic": "RATING"
}
```

#### Seed Event on Subscribe (`RATING_SEED`)

For every user in a successful subscribe call to the `RATING` topic, DUPR immediately posts one `RATING_SEED` event to your registered webhook URL with the player's current rating and metrics. This removes the need to wait for the next match before your application has usable rating data — your UI can render a player's rating the moment the subscribe request returns.

* The `event` field on the envelope is `RATING_SEED` (not `RATING`) so you can branch on it in your handler.
* The inner payload has the same shape as the `RATING` event (`duprId`, `name`, `timestamp`, `rating`, `metrics`). `matchId` inside `rating` is always null for a seed — there is no triggering match.
* Players with no rating yet (never played a rated match) still produce a seed, with `rating` and `metrics` both set to `null`. The envelope + `duprId` still arrive so you know the subscription is active.
* The seed fires on **every** successful subscribe call, not only the first. Unsubscribing and re-subscribing is the supported way to force a fresh seed for a player.
* Fetch the full schema from `GET /v1.0/webhook/schema/RATING_SEED` (see next section).

You cannot subscribe to `RATING_SEED` directly — it is produced only as a side-effect of subscribing to `RATING`, targeted solely at the partner who made the subscribe call.

#### Webhook Payload Schema

DUPR publishes a JSON schema for each webhook topic that covers the **full HTTP body** DUPR posts to your URL — outer envelope (`clientId`, `event`, `message`) and the topic-specific payload inside `message`, including every nested type. Fetch it to validate incoming bodies, code-gen deserialization types, or browse field-level descriptions (for example, the `careerHigh` "-1" sentinel semantics). The schema is generated at request time from the server's payload definitions — it is always in sync with what DUPR actually sends.

<table><thead><tr><th width="186">Environment</th><th>Manifest (list topics)</th><th>Per-topic schema</th></tr></thead><tbody><tr><td>UAT</td><td><code>GET https://uat.mydupr.com/api/v1.0/webhook/schema</code></td><td><code>GET https://uat.mydupr.com/api/v1.0/webhook/schema/{topic}</code></td></tr><tr><td>Production</td><td><code>GET https://prod.mydupr.com/api/v1.0/webhook/schema</code></td><td><code>GET https://prod.mydupr.com/api/v1.0/webhook/schema/{topic}</code></td></tr></tbody></table>

Both endpoints are unauthenticated and return `application/json`. The manifest response is a list of `{topic, href}` entries; the per-topic response follows the OpenAPI 3 `components.schemas` convention — the schema named by `rootSchemaName` is the full envelope, and `$ref` pointers resolve against `components.schemas`.

Example — fetch the current `RATING` envelope schema:

```bash
curl https://uat.mydupr.com/api/v1.0/webhook/schema/RATING
```

The `RATING_SEED` schema is published alongside `RATING` and returned by the same per-topic endpoint:

```bash
curl https://uat.mydupr.com/api/v1.0/webhook/schema/RATING_SEED
```

{% hint style="info" %}
Treat the schema endpoint as the authoritative source of the payload shape. New optional fields may be added over time and will appear in the schema without a breaking change — code against the schema, not against hard-coded samples.
{% endhint %}

***

## Troubleshooting

If you encounter errors during the webhook registration or subscribing to players, check the common causes below:

<table><thead><tr><th>Error</th><th width="185">Potential Cause</th><th>Potential Fix</th></tr></thead><tbody><tr><td>Webhook could not be registered due to the following error: The specified webhook did not respond with a 200 OK, returned a 404</td><td>The URL is invalid or did not respond with a <code>200 OK</code> during the handshake.</td><td>Ensure your URL is HTTPS, active, and returns <code>200 OK</code> immediately.</td></tr><tr><td>My webhook registered successfully, but I am not receiving any rating updates after subscribing to a user.</td><td>The clientId used during registration does not match your account.</td><td>Re-register the webhook using the correct client key.</td></tr><tr><td>Need to manually update a rating</td><td>Missed webhook events or sync issues.</td><td><a href="https://uat.mydupr.com/api/swagger-ui/index.html#/Users/userDetail">UAT: Get User Info</a><br><br><a href="https://prod.mydupr.com/api/swagger-ui/index.html#/Users/userDetail">Prod: Get User Info</a></td></tr><tr><td>Need to stop subscribing to a user's rating updates</td><td>User is no longer on my platform</td><td><p><a href="https://uat.mydupr.com/api/swagger-ui/index.html#/Users/unsubscribeUserWebhookEvent">UAT: Unsubscribe to User Webhook Event</a><br></p><p><a href="https://prod.mydupr.com/api/swagger-ui/index.html#/Users/unsubscribeUserWebhookEvent">Prod: Unsubscribe to User Webhook Event</a></p></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dupr.gitbook.io/dupr-raas/integration-checklist/ratings-and-webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.