# POST {callbackUrl} (callback)

> Callback to your callbackUrl

Rivr makes this call to your address. Answer 2xx once you have received it.

Rivr POSTs this body as JSON to the `callbackUrl` of an order (or subscription) every time the object changes status. Any 2xx response within 5 seconds acknowledges it. Otherwise Rivr makes at most 14 attempts within 7 days, each scheduled from the time the event was created; a response with status 400, 405, 410, 413, 414, 415, 422 is not retried. The full schedule is under Callback details in the introduction.

The callback is signed with `Rivr-Signature` when your merchant or platform has an active signing key. Verify it before you act on the body.

- Surface: `/api/public` · operationId `receiveCallback` · Group: Webhooks
- The spec: https://developers.rivr.io/openapi/api-public.json
- The spec's introduction: https://developers.rivr.io/reference/api-public.md
- Page in the portal: https://developers.rivr.io/reference/api-public/receiveCallback

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Rivr-Signature` | header | string | no | `t=<unix seconds>,v1=<signature>[,v1=<signature>…]`. Each `v1` is the lowercase hex HMAC-SHA256 of `"{t}.{raw body}"` with one of your active signing keys; there is one `v1` per active key on the merchant and on its platform, so a key can be rotated without a gap. Accept the callback when any `v1` matches a key you hold, compute it over the raw body exactly as received, and reject a `t` that is too old (for example more than five minutes). The header is only sent when the merchant or its platform has an active signing key; signing is optional on this delivery path. |

## Request body (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | – | The id of the object that changed: the order id you chose when you created the order, or the subscription id. |
| `type` | string | – | What kind of object changed: `Order`, `Invoice` (an order created as an invoice) or `Subscription`. |
| `merchantId` | string (uuid) | – | The merchant (clinic) the object belongs to. |
| `status` | string | – | The event. An order or invoice is `Created`, `Pending`, `Completed` (paid), `Cancelled` or `Refunded`; a subscription is `Inactive` or `Active`. |
| `data` | map<string, any> | – | Details for the event. Key names are written in PascalCase (for example `CompletedDate`); read them case-insensitively. Every order event carries `CreatedDate`, `Reference` and `Metadata`. `Completed` adds `CompletedDate` and `PaymentMethod`, `Cancelled` adds `CancelledDate` and `Reason`, and `Refunded` adds `RefundedDate`. A subscription carries `CreatedDate`, and when `Active` also `ActivatedDate`, `FirstPaymentDate`, `LastPaymentDate` and `IsActive`. New keys can be added without notice. |

**Example**

```json
{
  "id": "84c3c4ad-63d8-4d49-a4ff-ed57bbd40a39",
  "type": "Order",
  "merchantId": "11112222-aaaa-bbbb-cccc-ddddeeeeffff",
  "status": "Completed",
  "data": {
    "key": {}
  }
}
```

## Responses

### 2XX

The callback is acknowledged. No more attempts are made.