Skip to Content
Getting StartedWeb App Integration

Web App Integration

Integrate your web application with the Loop comms platform to send transactional messages, track events, and manage communication workflows.

Install @loop/contracts

Add the contracts package to your project:

pnpm add @loop/contracts

This gives you typed, versioned event schemas and the validateEvent() helper for compile-time and runtime safety.

Declare Events

Before firing events, declare their schema with the comms platform. This registers the event type and enables template binding, routing rules, and analytics.

import { LeadCapturedV1 } from '@loop/contracts';

Use the MCP tool events.declare or the REST API to register a new event type:

{
  "tool": "events.declare",
  "input": {
    "name": "lead.captured.v1",
    "schema": {
      "email": "string",
      "source": "enum(vsl_form|quiz_completion|inbound_lead|other)",
      "brandId": "uuid"
    }
  }
}

Fire Transactional Events

Once an event is declared, fire it from your app whenever the corresponding action occurs:

const response = await fetch('https://comms.loop.health/api/events', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${API_KEY}`,
  },
  body: JSON.stringify({
    event: 'lead.captured.v1',
    payload: {
      eventId: crypto.randomUUID(),
      occurredAt: new Date().toISOString(),
      brandId: 'your-brand-uuid',
      email: 'user@example.com',
      source: 'vsl_form',
      attribution: {
        utm_source: 'google',
        utm_medium: 'cpc',
      },
      personId: null,
    },
  }),
});

Validate Before Sending

Use validateEvent() to catch schema errors before they hit the network:

import { validateEvent } from '@loop/contracts';
 
const result = validateEvent('lead.captured.v1', payload);
if (!result.success) {
  console.error('Validation failed:', result.error);
  return;
}

Embed Tracking

Add the Loop tracking snippet to your pages to capture page views, form submissions, and attribution data automatically:

<script src="https://comms.loop.health/tracking.js" data-brand="your-brand-uuid" async></script>

The tracker captures:

SignalDescription
Page viewsURL, referrer, time on page
Form submissionsField values on submit (opt-in per form)
UTM parametersAutomatically extracted from query string
Click IDsirclickid, gclid, fbclid from query string

Configure Webhooks

Register webhook endpoints to receive delivery events from the comms platform:

{
  "url": "https://your-app.com/webhooks/comms",
  "events": [
    "message.sent.v1",
    "message.delivered.v1",
    "message.bounced.v1"
  ],
  "secret": "whsec_..."
}

Verify Webhook Signatures

All webhook payloads include an X-Loop-Signature header. Verify it to ensure authenticity:

import { verifyWebhookSignature } from '@loop/contracts';
 
const isValid = verifyWebhookSignature(
  req.headers['x-loop-signature'],
  req.body,
  WEBHOOK_SECRET
);

Retry Policy

Failed webhook deliveries are retried with exponential backoff:

AttemptDelay
1Immediate
230 seconds
32 minutes
410 minutes
51 hour

After 5 failures, the endpoint is marked degraded and an alert is sent to the ops channel.

Next Steps

ArchitectureMobile Integration