Handle Webhooks

This guide shows how to receive and verify webhook events from the Loop Platform.

Who this is for

Developers building applications that need real-time notifications when data changes on the platform — for example, when a biomarker result arrives or a protocol is started.

How Webhooks Work

You register a webhook URL in your app’s settings on the developer portal.
When an event occurs that your app has scopes for, the platform sends an HTTP POST to your URL.
Your server verifies the signature and processes the event.

Setting Up an Endpoint

Node.js (Express)

import express from "express";
import crypto from "node:crypto";
 
const app = express();
app.use(express.raw({ type: "application/json" }));
 
app.post("/webhooks/loop", (req, res) => {
  const signature = req.headers["x-loop-signature"] as string;
  const expected = crypto
    .createHmac("sha256", process.env.WEBHOOK_SECRET!)
    .update(req.body)
    .digest("hex");
 
  if (signature !== expected) {
    return res.status(401).send("Invalid signature");
  }
 
  const event = JSON.parse(req.body.toString());
 
  switch (event.type) {
    case "biomarker.result.created":
      // Handle new biomarker result
      break;
    case "protocol.started":
      // Handle protocol start
      break;
  }
 
  res.status(200).send("OK");
});

Python (Flask)

import hmac
import hashlib
from flask import Flask, request
 
app = Flask(__name__)
 
@app.post("/webhooks/loop")
def handle_webhook():
    signature = request.headers.get("X-Loop-Signature")
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        request.data,
        hashlib.sha256,
    ).hexdigest()
 
    if signature != expected:
        return "Invalid signature", 401
 
    event = request.json
    # Process event...
    return "OK", 200

Verifying Signatures

Every webhook request includes an X-Loop-Signature header containing an HMAC-SHA256 hex digest of the request body, signed with your webhook secret. Always verify this signature before processing the event.

Retry Policy

If your endpoint returns a non-2xx status code, the platform retries with exponential backoff: 1 minute, 5 minutes, 30 minutes, 2 hours, 24 hours. After 5 failed attempts, the webhook is marked as failing and an alert is sent.

Next Steps

Webhooks Reference — Full webhook event catalog and configuration.
Scopes — Events are filtered by the scopes your app was granted.

Use a Service from Your App Style Guide