# Rewards and webhooks

When a user becomes eligible for a reward, the Platform presents the claim action. Onward validates the claim and asks the configured Reward Provider to deliver the reward.

<Mermaid
  chart={`sequenceDiagram
    participant User
    participant Platform
    participant Onward as Onward API
    participant RewardProvider as Reward Provider

    User->>Platform: Claim reward
    Platform->>Onward: Submit reward claim
    Onward->>Onward: Validate eligibility and idempotency
    Onward->>RewardProvider: Signed reward webhook
    RewardProvider->>RewardProvider: Deliver reward idempotently
    RewardProvider-->>Onward: Delivery result
    Onward-->>Platform: Claim result
    Platform-->>User: Show updated reward state`}
  caption="Reward delivery across the Platform, Onward, and the configured Reward Provider."
/>

## Provider responsibilities

- Expose an HTTPS webhook endpoint.
- Verify the webhook signature before parsing or applying the request.
- Use the raw request body when calculating the signature.
- Enforce timestamp freshness to prevent replay attacks.
- Make reward delivery idempotent.
- Return quickly and perform slow downstream work asynchronously when possible.
- Log delivery identifiers without recording secrets.

## Signature verification

The existing integration uses an HMAC-SHA256 signature with a timestamp. The signed value is constructed from the timestamp and exact raw JSON body:

```text
HMAC-SHA256(webhook_secret, "<timestamp>.<raw_json_body>")
```

Use constant-time comparison and reject stale timestamps. A five-minute tolerance is a sensible default unless your integration agreement specifies another value.

:::note
Reward claim and webhook contracts are described here as workflow context. They will be added to the generated [API Reference](/docs/api-reference) after their runtime schemas are promoted to the public OpenAPI document.
:::