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

# Webhooks

> Receive real-time event notifications for your app.

Webhooks allow your app to receive real-time notifications when events occur in a merchant's store. Instead of polling the API for changes, OrderProtection pushes events to your server as they happen.

## Configuring webhooks

When [creating](/developer/creating-an-app) or editing your app, you can configure:

1. **Webhook URL** — The HTTPS endpoint on your server that will receive webhook payloads
2. **Webhook Topics** — The event types you want to subscribe to

When a merchant installs your app, OrderProtection automatically registers your configured webhooks for that store. When the merchant uninstalls, the webhooks are automatically removed.

## Webhook delivery

When an event occurs, OrderProtection sends an HTTP POST request to your webhook URL:

```bash theme={null}
POST https://yourapp.example.com/webhook
Content-Type: application/json
x-webhook-secret: <your-webhook-secret>
```

```json theme={null}
{
  "topic": "claim/approved",
  "body": {
    "claimId": "claim_abc123",
    "storeId": "store_xyz789",
    "resolutions": [
      {
        "type": "RESHIP",
        "itemId": "item_123",
        "quantity": 1
      }
    ]
  }
}
```

## Authentication

Every webhook request includes an `x-webhook-secret` header. Use this secret to verify that the request originated from OrderProtection and has not been tampered with.

```javascript theme={null}
app.post("/webhook", (req, res) => {
  const secret = req.headers["x-webhook-secret"];

  if (secret !== process.env.WEBHOOK_SECRET) {
    return res.status(401).send("Unauthorized");
  }

  const { topic, body } = req.body;
  // Handle the event...

  res.status(200).send("OK");
});
```

<Warning>
  Always validate the `x-webhook-secret` header before processing webhook payloads. Requests without a valid secret should be rejected.
</Warning>

## Available topics

### Claims

| Topic            | Description                                       |
| ---------------- | ------------------------------------------------- |
| `claim/created`  | A new claim has been filed                        |
| `claim/approved` | A claim has been approved with resolution details |
| `claim/denied`   | A claim has been denied                           |

### Messages

| Topic             | Description                       |
| ----------------- | --------------------------------- |
| `message/created` | A new message was sent on a claim |

### Protection

| Topic                | Description                          |
| -------------------- | ------------------------------------ |
| `protection/added`   | Protection was added to an order     |
| `protection/removed` | Protection was removed from an order |

<Note>
  For detailed payload schemas for each webhook topic, see the [Webhooks reference](/webhooks/introduction).
</Note>

## Best practices

* **Respond quickly** — Return a `200` status code within 5 seconds. If you need to do heavy processing, acknowledge the webhook and handle the work asynchronously.
* **Handle duplicates** — Webhooks may occasionally be delivered more than once. Use the event ID or resource ID to deduplicate.
* **Use HTTPS** — Your webhook URL must use HTTPS in production to ensure payloads are encrypted in transit.