Webhooks

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 or editing your app, you can configure:

Webhook URL — The HTTPS endpoint on your server that will receive webhook payloads
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:

POST https://yourapp.example.com/webhook
Content-Type: application/json
x-webhook-secret: <your-webhook-secret>

{
  "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.

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");
});

Always validate the x-webhook-secret header before processing webhook payloads. Requests without a valid secret should be rejected.

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

App lifecycle

Topic	Description
`app/uninstalled`	A store uninstalled your app

app/uninstalled behaves differently from the event topics above: it is delivered directly to your app’s webhook URL for every installation, the moment you add the topic to your app’s webhook settings — no per-store registration involved. By the time it arrives, the installation’s tokens are already revoked. Body:

{
  "application_id": "cmslq2gzg0004mss8agayocuu",
  "client_id": "op_app_...",
  "store_id": "cms6hqe230006gifyusgheils",
  "installation_id": "cmt0...",
  "uninstalled_at": "2026-08-11T18:00:00.000Z"
}

There is no app/installed topic — on a marketplace install your redirect URI already receives the authorization code (see Installing Your App), and on an API install your backend is the caller.

For detailed payload schemas for each webhook topic, see the Webhooks reference.

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.

Getting Started

Authentication

Analytics

Distribution

Reference

Configuring webhooks

Webhook delivery

Authentication

Available topics

Claims

Messages

Protection

App lifecycle

Best practices

​Configuring webhooks

​Webhook delivery

​Authentication

​Available topics

​Claims

​Messages

​Protection

​App lifecycle

​Best practices

Configuring webhooks

Webhook delivery

Authentication

Available topics

Claims

Messages

Protection

App lifecycle

Best practices