Webhooks

Loops sends an HTTPS POST to your endpoint when something happens: a new order, a status change, a merchant connecting or leaving.

Set up an endpoint

In the Loops Partners portal, open Webhooks → Add endpoint:

• give an HTTPS URL;
• choose the events to receive (wildcards such as order.* work);
• copy the endpoint’s signing secret.

Use Send test event to check your endpoint end to end.

What you receive

POST /loops/webhooks HTTP/1.1
Content-Type: application/json
webhook-id: evt_01J9C2X4RS
webhook-timestamp: 1791100800
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{
  "id": "evt_01J9C2X4RS",
  "type": "order.status_changed",
  "created_at": "2026-10-04T12:02:11Z",
  "merchant_id": "mer_7Hq2Lw8Z",
  "location_id": "loc_2Xf9K",
  "connection_id": "con_4Tz8Yp1W",
  "origin": { "type": "channel", "application_id": null },
  "data": {
    "order_id": "ord_01J9QW3T8M",
    "channel_ref": "CH-88213",
    "previous_status": "placed",
    "status": "accepted",
    "version": 3
  }
}

Verify the signature

Requests are signed with the Standard Webhooks scheme, so you can use the official libraries. Always verify before trusting the body. Reject requests whose timestamp is more than 5 minutes old; the libraries do this for you.

Node.js

import { Webhook } from "standardwebhooks";

const wh = new Webhook(process.env.LOOPS_WEBHOOK_SECRET);

// Use the raw body: re-serialized JSON breaks the signature.
app.post("/loops/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = wh.verify(req.body, req.headers);
  } catch {
    return res.sendStatus(400);
  }
  queue.push(event);
  res.sendStatus(200);
});

Python

from standardwebhooks.webhooks import Webhook, WebhookVerificationError

wh = Webhook(os.environ["LOOPS_WEBHOOK_SECRET"])

@app.post("/loops/webhooks")
def loops_webhook(request):
    try:
        event = wh.verify(request.body, request.headers)
    except WebhookVerificationError:
        return "", 400
    queue.put(event)
    return "", 200

PHP

use StandardWebhooks\Webhook;

$wh = new Webhook(getenv('LOOPS_WEBHOOK_SECRET'));
$payload = file_get_contents('php://input');

try {
    $event = $wh->verify($payload, getallheaders());
} catch (Exception $e) {
    http_response_code(400);
    exit;
}
// enqueue $event, then:
http_response_code(200);

Process reliably

• Reply fast. Return a 2xx within 10 seconds, then process the event in the background. Slow responses count as failures.
• Expect duplicates. Delivery is at least once. Store each webhook-id, and skip IDs you’ve already handled.
• Expect any order. Use version (orders) or created_at to ignore stale events.
• Ignore your own changes. When origin.application_id is your application, the event reflects something you did.

Retries

If your endpoint fails or times out, Loops retries. Attempt 1 is sent immediately; each later attempt waits after the previous one:

Attempt	2	3	4	5	6	7	8
Wait	10 s	1 min	5 min	30 min	2 h	6 h	12 h

• After about 21 hours the delivery is marked failed. The event stays available through the Events API for 30 days.
• An endpoint that keeps failing for 3 days is disabled, and your team is emailed. Re-enable it in the portal, then catch up with GET /v1/events?after=….

تنبيه

Webhooks are the fast path, not the only path. Always be able to recover from the Events API, because no webhook system can guarantee your endpoint is up.

See the event reference for every event type.