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 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:

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

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.