> ## Documentation Index
> Fetch the complete documentation index at: https://developers.opereit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Headers, body, and expected response of every webhook event

Every webhook is a `POST` to your endpoint with a JSON body. The `type` field says which event it is, and `data` is the entity the event is about. See the [webhooks guide](https://developers.opereit.ai/guides/webhooks.md) for setup, delivery, and signature verification.

## Headers

**webhook-id** `string` *required*

Unique event ID. Same value as the body `id`, and stays the same across retries.

**webhook-timestamp** `string` *required*

When this delivery attempt was sent, in Unix seconds.

**webhook-signature** `string` *required*

Space-separated list of `v1,<base64 HMAC-SHA256>` signatures. See [Verify signatures](https://developers.opereit.ai/guides/webhooks.md#verify-signatures).

## Body

**id** `string` *required*

Unique event ID. Same value as the `webhook-id` header.

**type** `string` *required*

The event type. One of the event types below.

**occurred\_at** `string` *required*

When the change happened, in ISO 8601 UTC. Retries keep the original value.

**data** `object` *required*

The entity the event is about, after the change. Its fields depend on `type`.

### Event types

> [accordion] `claim.status_updated`
>
> Sent every time a claim's `status` or `status_reason` changes, including a change to the status reason alone. The fields below are the content of `data` in the webhook body.
>
> **data.id** `string` *required*
>
> Unique claim ID. Use it with [`GET /v1/claims/{id}`](https://developers.opereit.ai/api-reference/endpoint/claims/get).
>
> **data.number** `string | null` *required*
>
> The carrier's claim reference, if one is assigned yet.
>
> **data.carrier\_id** `string` *required*
>
> Carrier identifier.
>
> **data.status** `enum\<string\>` *required*
>
> The claim's status after the change. One of `CREATED`, `UNDER_REVIEW`, `PENDING_ACTION`, `PENDING_REFUND`, `PENDING_REFUND_AMOUNT_CONFIRMED`, `RESOLVED`, `CANCELED`, `REJECTED`, or `CLOSED`. See [What happens after you create a claim](https://developers.opereit.ai/guides/claims.md#what-happens-after-you-create-a-claim).
>
> **data.status\_reason** `object | null` *required*
>
> Set when `status` is `PENDING_ACTION`, `CANCELED`, or `REJECTED`. `null` for every other status. See [Status reasons](https://developers.opereit.ai/guides/claims.md#status-reasons).
>
> **properties**
>
> **id** `string` *required*
>
> Unique ID of this status reason.
>
> **slug** `string` *required*
>
> Stable code of the reason, for example `CUSTOMER_ACTION_REQUIRED_DAMAGE_PROOF`.
>
> **label** `string` *required*
>
> Human-readable label for the reason.
>
> **data.shipment** `object` *required*
>
> The claimed shipment.
>
> **properties**
>
> **tracking\_number** `string` *required*
>
> Tracking number of the claimed shipment.
>
> **data.metadata** `object` *required*
>
> The key-value pairs you sent when you created the claim, returned unchanged. Keys and values are strings. An empty object if you sent none.
>
> ```json Example theme={null}
> {
>   "id": "evt_2pXk8cQb7L",
>   "type": "claim.status_updated",
>   "occurred_at": "2026-11-02T10:15:30.123Z",
>   "data": {
>     "id": "clm_3Ccox6eQUYYeg9RIo6qXCwGN3nQ",
>     "number": "UPS-123456789",
>     "carrier_id": "b2e4d6f8-1a3c-4e5b-8d7f-9c0a2b4d6e81",
>     "status": "PENDING_ACTION",
>     "status_reason": {
>       "id": "rjr_4nB8vC2wQe",
>       "slug": "CUSTOMER_ACTION_REQUIRED_DAMAGE_PROOF",
>       "label": "You need to provide proof of damage"
>     },
>     "shipment": {
>       "tracking_number": "1Z999AA10123456784"
>     },
>     "metadata": {
>       "order_id": "6735",
>       "store": "ES-01"
>     }
>   }
> }
> ```

## Response

Return any `2xx` status within 10 seconds to acknowledge the event. The response body is ignored. Any other status, a timeout, or a connection error is retried with exponential backoff.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.