> For the complete documentation index, see [llms.txt](https://dupr.gitbook.io/dupr-raas/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dupr.gitbook.io/dupr-raas/integration-checklist/ratings-and-webhooks.md).

# 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>