Webhooks - Loops

Webhooks is currently in Alpha, please let the team know via a suppport channel if you’d like early access.

Webhooks send data to your website or application when certain events happen in your Loops account.

Set up webhooks

Go to Settings -> Webhooks and input the URL of your endpoint that will receive events.

You will be provided with a signing secret. You should save this in your project (for example in an environment variable) so you can verify requests when you receive them.

Currently you can only set up one webhook endpoint per Loops account.

Subscribe to the events you want to receive using the toggles. Click the group names to view all events in each.

When toggling your endpoint on and off there may be a small delay before this setting is reflected on the server. For example, it may take a few seconds after toggling on your endpoint for requests to be dispatched.

Rate limiting

Webhook events will be sent at a maximum rate of 10 per second. Any further events will be queued.

Verify requests

Every event is signed so you can check that data sent to your endpoint is sent from Loops.

To verify webhooks, you need to create a signature of the received request and match that to the provided signature in the request’s headers.

Here’s an example verification function you could use in Next.js:

import { NextRequest } from 'next/server';
import crypto from 'crypto';

interface WebhookVerificationError extends Error {
  code: 'MISSING_HEADERS' | 'MISSING_SECRET' | 'INVALID_SIGNATURE' | 'VERIFICATION_FAILED';
}

/**
 * Verifies a webhook request from Loops
 * @param req The incoming Next.js request
 * @throws {WebhookVerificationError} If verification fails
 * @returns {Promise<boolean>} True if verification succeeds
 */
async function verifyWebhook(req: NextRequest): Promise<boolean> {
  try {

    // Get the webhook-related headers directly from req.headers
    // Next.js automatically lowercases header names
    const eventId = req.headers.get('webhook-id');
    const timestamp = req.headers.get('webhook-timestamp');
    const webhookSignature = req.headers.get('webhook-signature');

    // Verify required headers are present
    if (!eventId || !timestamp || !webhookSignature) {
      const error = new Error('Missing required webhook header') as WebhookVerificationError;
      error.code = 'MISSING_HEADERS';
      throw error;
    }
    
    // Read raw body as buffer
    const readable = req.read();
    const buffer = Buffer.from(readable);
    const rawBodyText = buffer.toString();

    const signedContent = `${eventId}.${timestamp}.${rawBodyText}`;

    // Verify secret exists
    const secret = process.env.LOOPS_SIGNING_SECRET;
    if (!secret) {
      const error = new Error(
        'Missing LOOPS_SIGNING_SECRET environment variable'
      ) as WebhookVerificationError;
      error.code = 'MISSING_SECRET';
      throw error;
    }
    // Create a signature from the request data
    const secretBytes = Buffer.from(secret.split('_')[1], 'base64');
    const signature = crypto
      .createHmac('sha256', secretBytes)
      .update(signedContent)
      .digest('base64');

    // Check if the signature matches
    const signatureFound = webhookSignature
      .split(' ')
      .some((sig) => sig.includes(`,${signature}`));

    if (!signatureFound) {
      const error = new Error('Invalid signature') as WebhookVerificationError;
      error.code = 'INVALID_SIGNATURE';
      throw error;
    }

    return true;
  } catch (error) {
    if ((error as WebhookVerificationError).code) {
      throw error;
    }
    const wrappedError = new Error(
      `Webhook verification failed: ${(error as Error).message}`
    ) as WebhookVerificationError;
    wrappedError.code = 'VERIFICATION_FAILED';
    throw wrappedError;
  }
}

Testing webhooks

From the Webhooks settings page you can send a test request to your endpoint. This allows you to test that your endpoint is working, and that your verification code is OK.

The event name sent during testing is testing.testEvent. You can see the payload below.

Viewing webhook history

Once Loops has started sending webhook events to your endpoint you will be able to see event history in the Messages section at the bottom of the Webhooks settings page.

Clicking on an event in the table will reveal the response from your endpoint, which is helpful if there have been any errors.

Event data

Every webhook will contain the following data in the request body:

`eventName`

The event type. See a full list of events below.

`webhookSchemaVersion`

Will be 1.0.0 for all events.

`eventTime`

Unix timestamp of the time the event occured in Loops.

Depending on the context of the event, more data will also be included. Full examples are shown in the Event types section below.

`contact`

A full contact object containing a contact’s properties.

Contains:

id
email
firstName (nullable string)
lastName (nullable string)
source
subscribed (boolean)
userGroup
userId (nullable string)
mailingLists (list of mailingList objects. See below)
plus any custom contact properties

This object is the same as the data returned in the Find a contact API endpoint.

`contactIdentity`

A contact’s identifiers. To retrieve the full contact, use the Find a contact API endpoint.

Contains:

id
email
userId (nullable string)

`email`

Details about an individual email send to a recipient:

id - The unqiue ID of the email.
emailMessageId - The ID of the sent version of the campaign/loop/transactional email.
subject - The subject of the sent version of the campaign/loop/transactional email.

To get the ID of the campaign, loop or transactional email that relates to the Loops dashboard or API, look for a campaignId, loopId, or transactionalId in the payload.

`mailingList`

Details about a mailing list:

id
name
description (nullable string)
isPublic (boolean)

This object is the same as the data returned in the List mailing lists API endpoint.

`mailingLists`

A list of mailingList objects (see above), when an event relates to multiple mailing lists.

`sourceType`

For email.* events, this specifies the type of email.

One of campaign, loop or transactional.

Headers

Headers will include:

Webhook-Signature - A list of request signatures, which can be used to verify the request.
Webhook-Id - The unique ID of the event. You can use this to check if you have already saved or processed this specific event.
Webhook-Timestamp - The timestamp of the request (seconds since epoch).

Event types

Contacts

contact.created

Sent when a new contact is created in your audience.

Contains a contactIdentity object plus a full contact object, which includes all of the new contact’s properties.

{
  "eventName": "contact.created",
  "eventTime": 1734425918,
  "webhookSchemaVersion": "1.0.0",
  "contactIdentity": {
    "id": "cm4itta800003ow9hhekzk94o",
    "email": "[email protected]",
    "userId": null
  },
  "contact": {
    "id": "cm4itta800003ow9hhekzk94o",
    "email": "[email protected]",
    "firstName": null,
    "lastName": null,
    "source": "API",
    "subscribed": true,
    "userGroup": "",
    "userId": null,
    "favoriteColor": "blue",
    "favoriteNumber": 42,
    "mailingLists": [
      {
        "id": "cm4ittp2k000l12j3lgrzvlxt",
        "name": "test mailing list",
        "description": null,
        "isPublic": true
      }
    ]
  }
}

contact.unsubscribed

Sent when

a contact is unsubscribed from your audience.
a contact is deleted from your audience (alongside contact.deleted).

This is not the same as a contact unsubscribing from a mailing list.
See contact.mailingList.unsubscribed).

Contains a contactIdentity object.

{
  "eventName": "contact.unsubscribed",
  "eventTime": 1734425918,
  "webhookSchemaVersion": "1.0.0",
  "contactIdentity": {
    "id": "cm4ittmhq0011ow9h6fb460yw",
    "email": "[email protected]",
    "userId": null
  }
}

contact.deleted

Sent when a contact is deleted from your audience.

Contains a contactIdentity object.

{
  "eventName": "contact.deleted",
  "eventTime": 1734425918,
  "webhookSchemaVersion": "1.0.0",
  "contactIdentity": {
    "id": "cm4ittmhq0011ow9h6fb460yw",
    "email": "[email protected]",
    "userId": null
  }
}

contact.mailingList.subscribed

Sent when a contact is subscribed to a mailing list.

Contains contactIdentity and mailingList objects.

{
  "eventName": "contact.mailingList.subscribed",
  "eventTime": 1734425918,
  "webhookSchemaVersion": "1.0.0",
  "contactIdentity": {
    "id": "cm4ittmhq0011ow9h6fb460yw",
    "email": "[email protected]",
    "userId": null
  },
  "mailingList": {
    "id": "cm4ittp2k000l12j3lgrzvlxt",
    "name": "test mailing list",
    "description": null,
    "isPublic": true
  }
}

contact.mailingList.unsubscribed

Sent when a contact is unsubscribed from a mailing list.

This is not the same as a contact unsubscribing from your audience.
See contact.unsubscribed.

Contains contactIdentity and mailingList objects.

{
  "eventName": "contact.mailingList.unsubscribed",
  "eventTime": 1734425918,
  "webhookSchemaVersion": "1.0.0",
  "contactIdentity": {
    "id": "cm4ittmhq0011ow9h6fb460yw",
    "email": "[email protected]",
    "userId": null
  },
  "mailingList": {
    "id": "cm4ittp2k000l12j3lgrzvlxt",
    "name": "test mailing list",
    "description": null,
    "isPublic": true
  }
}

Email sending

campaign.email.sent

Sent when a campaign is sent to a contact.

This event will fire for every campaign send. If you send a campaign to 1,000 contacts, you will receive 1,000 events.

Contains a campaignId value plus contactIdentity and email objects.

If the campaign was sent to one or more mailing lists, a mailingLists list will also be included.

{
  "eventName": "campaign.email.sent",
  "eventTime": 1734425918,
  "webhookSchemaVersion": "1.0.0",
  "contactIdentity": {
    "id": "cm4ittmhq0011ow9h6fb460yw",
    "email": "[email protected]",
    "userId": null
  },
  "campaignId": "cm4t1suns001uw6atri87v54s",
  "email": {
    "id": "cm4t1sv84004yje79hawr1fi1",
    "emailMessageId": "cm4t1suns001ww6atotin3bn1",
    "subject": "Test Subject"
  },
  "mailingLists": [
    {
      "id": "cm4ittp2k000l12j3lgrzvlxt",
      "name": "test mailing list",
      "description": null,
      "isPublic": true
    }
  ]
}

loop.email.sent

Sent when a loop email is sent to a contact.

This event will fire for every contact in a loop. If 1,000 contacts get sent emails from your loop, you will receive 1,000 events.

Contains a loopId value plus contactIdentity and email objects.

If the loop was sent to one or more mailing lists, a mailingLists list will also be included.

{
  "eventName": "loop.email.sent",
  "eventTime": 1734425918,
  "webhookSchemaVersion": "1.0.0",
  "contactIdentity": {
    "id": "cm4ittmhq0011ow9h6fb460yw",
    "email": "[email protected]",
    "userId": null
  },
  "loopId": "cm4t1snfj0052icemfshgqfcw",
  "email": {
    "id": "cm4t1socj004mje79e61mgh7d",
    "emailMessageId": "cm4ittv1v001oow9hruou8na8",
    "subject": "Subject of the email"
  },
  "mailingLists": [
    {
      "id": "cm4ittp2k000l12j3lgrzvlxt",
      "name": "test mailing list",
      "description": null,
      "isPublic": true
    }
  ]
}

transactional.email.sent

Sent when a transactional email is sent.

Contains a transactionalId value plus contactIdentity and email objects.

{
  "eventName": "transactional.email.sent",
  "eventTime": 1734425918,
  "webhookSchemaVersion": "1.0.0",
  "contactIdentity": {
    "id": "cm4ittmhq0011ow9h6fb460yw",
    "email": "[email protected]",
    "userId": null
  },
  "transactionalId": "cm4t1suns001uw6atri87v54s",
  "email": {
    "id": "cm4t1sseg004tje7982991nan",
    "emailMessageId": "cm4ittv1v001oow9hruou8na8",
    "subject": "Subject of the email"
  }
}