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

# Webhooks

> Get a signed request at your URL when an order is paid, refunded or shipped.

Register a URL and Replo sends it a signed `POST` each time something happens in your project, so your warehouse, ERP or automation hears about orders and packages without polling. Webhooks are in beta and need API version `2026-11-17`.

## Before you begin

* A public `https` URL that answers within 10 seconds. Replo refuses URLs that resolve to a private network.
* To manage endpoints through the API, a project API key with `webhooks.read` and `webhooks.write`. You can also manage them in **Settings → Developers → Webhooks**.

## Add an endpoint

```bash theme={null}
curl https://api.replo.app/v1/webhook-endpoints \
  -H "Authorization: Bearer $REPLO_API_KEY" \
  -H "Replo-Api-Version: 2026-11-17" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "3d2c…",
    "url": "https://example.com/replo",
    "events": ["order.paid", "fulfillment.created", "fulfillment.updated"],
    "description": "Warehouse sync"
  }'
```

The response carries `secret` (`whsec_…`) once. Store it: Replo keeps it encrypted and never shows it again. An empty `events` list sends every event type.

Each endpoint is pinned to the API version current when you created it (`apiVersion`). Payloads keep that shape for the endpoint's whole life, so a later API version never changes what your code receives. To move to a newer version, add a new endpoint and delete the old one.

## Event types

| Type | Sent when | `data` holds |
| - | - | - |
| `order.paid` | An order's payment succeeds | Order |
| `order.updated` | An order changes, such as a note added or part of it cancelled | Order |
| `order.refunded` | An order is refunded in full or in part. Sent once per refunded total, whether the refund started in Replo or Stripe | Order |
| `order.cancelled` | An order is cancelled: nothing on it is left to ship | Order |
| `fulfillment.created` | Items are marked shipped, by any tool: Replo, ShipStation, a CSV import or the API. A local pickup order marked ready for pickup also counts | Fulfillment |
| `fulfillment.updated` | Tracking changes, a carrier scan changes where a package is, or a pickup order is picked up | Fulfillment |
| `fulfillment.cancelled` | A package is cancelled or its label voided | Fulfillment |
| `shipping_label.purchased` | A label is bought in Replo | Shipping label |
| `shipping_label.voided` | The carrier confirms a label is voided | Shipping label |

`data` is the same object the matching `GET` returns in the endpoint's API version: [`GET /v1/orders/{orderId}`](https://docs.replo.app/api-reference/introduction) for order events, and one item of `GET /v1/orders/{orderId}/fulfillments` for fulfillment events. It's read when the request is sent, so it reflects the resource at that moment, not only the change that triggered it.

## The request

```http theme={null}
POST /replo HTTP/1.1
Content-Type: application/json
User-Agent: Replo-Webhooks/1.0
Replo-Webhook-Id: 1c9f2b6e-…
Replo-Webhook-Timestamp: 1794506651
Replo-Webhook-Signature: v1=5257a8…
Replo-Webhook-Event: fulfillment.updated

{
  "id": "1c9f2b6e-…",
  "type": "fulfillment.updated",
  "created": "2026-11-14T16:22:09.000Z",
  "apiVersion": "2026-11-17",
  "projectId": "3d2c…",
  "data": {
    "object": "fulfillment",
    "id": "5f0d…",
    "orderId": "7c1e…",
    "source": "api",
    "trackingCarrier": "FedEx",
    "trackingNumber": "794644102245",
    "shipmentStatus": "inTransit",
    "updatedAt": "2026-11-14T16:22:08.000Z"
  }
}
```

| Header | Value |
| - | - |
| `Replo-Webhook-Id` | The event's id, also the body's `id`. The same on every retry. |
| `Replo-Webhook-Timestamp` | Unix seconds when this attempt was signed. |
| `Replo-Webhook-Signature` | `v1=` and the hex HMAC-SHA256 of `{timestamp}.{raw body}`, keyed with the endpoint's secret. |
| `Replo-Webhook-Event` | The event type, also the body's `type`. |

## Check the signature

Verify every request before you trust it. Sign the raw body exactly as received, before any JSON parsing, compare in constant time, and reject timestamps more than five minutes old so a captured request can't be replayed.

```js theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

const app = express();
const secret = process.env.REPLO_WEBHOOK_SECRET; // whsec_…

app.post("/replo", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.header("Replo-Webhook-Timestamp") ?? "";
  const signature = req.header("Replo-Webhook-Signature") ?? "";
  const body = req.body.toString("utf8");

  const expected = `v1=${createHmac("sha256", secret)
    .update(`${timestamp}.${body}`)
    .digest("hex")}`;
  const isFresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
  const isValid =
    signature.length === expected.length &&
    timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  if (!isFresh || !isValid) {
    return res.sendStatus(400);
  }

  const event = JSON.parse(body);
  // Queue the work and answer right away.
  res.sendStatus(200);
});
```

## Answer, retries and ordering

* **Answer with a `2xx` within 10 seconds.** Do slow work after you answer. A timeout, a connection error, any other status, or a redirect counts as a failed attempt. Replo doesn't follow redirects and doesn't read your response body.
* **Retries.** A failed delivery is tried 8 times in all, about 24 hours: again after 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours, 8 hours and 8 hours. After the eighth failure it stops and the delivery shows as failed. Send it again from the delivery log or with `POST /v1/webhook-deliveries/{webhookDeliveryId}/redeliver`, which restarts the schedule.
* **Duplicates.** A request can arrive more than once. Use `Replo-Webhook-Id` as a dedupe key.
* **Ordering isn't guaranteed.** Two events about the same package can arrive out of order. For fulfillments, ignore an event whose `data.updatedAt` is older than what you already have. For orders, compare the body's `created`, or fetch the order again.
* **Turned off after 7 days of failures.** An endpoint with no successful delivery for 7 days is turned off (`enabled: false`, `disabledReason: "failing"`) and the person who created it gets an email. Fix your endpoint, then turn it back on in Settings or with `PATCH /v1/webhook-endpoints/{webhookEndpointId}` and `{"enabled": true}`. Deliveries still waiting for a retry are sent within the hour; failed ones can be sent again from the delivery log.

## Manage endpoints

| Task | Route | Scope |
| - | - | - |
| List or get endpoints | `GET /v1/webhook-endpoints?projectId=…`, `GET /v1/webhook-endpoints/{webhookEndpointId}` | `webhooks.read` |
| Change the URL, events or description, turn off or on | `PATCH /v1/webhook-endpoints/{webhookEndpointId}` | `webhooks.write` |
| Make a new signing secret | `POST /v1/webhook-endpoints/{webhookEndpointId}/rotate-secret` | `webhooks.write` |
| See deliveries | `GET /v1/webhook-endpoints/{webhookEndpointId}/deliveries` | `webhooks.read` |
| Send a delivery again | `POST /v1/webhook-deliveries/{webhookDeliveryId}/redeliver` | `webhooks.write` |
| Delete an endpoint | `DELETE /v1/webhook-endpoints/{webhookEndpointId}` | `webhooks.write` |

Rotating takes effect on the next request, so deploy code that accepts the new secret first. A project can have up to 16 endpoints.

In **Settings → Developers → Webhooks** you can also send a test event: a sample `fulfillment.updated`, signed like a real one, with your server's answer shown right away.

> [card] [Ship from your own tool](https://docs.replo.app/developers/shipping.md)
>
> Mark orders shipped and keep tracking in sync through the API.

> [card] [Versioning](https://docs.replo.app/api-reference/versioning.md)
>
> How API versions and pinned payloads work.


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