Skip to main content
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

TopicDescription
claim/createdA new claim has been filed
claim/approvedA claim has been approved with resolution details
claim/deniedA claim has been denied

​
Messages

TopicDescription
message/createdA new message was sent on a claim

​
Protection

TopicDescription
protection/addedProtection was added to an order
protection/removedProtection 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.