[ Web Proxy ]
URL:
Viewing: https://userlist.com/docs/developers/webhooks/ [Back]  [Original]
Webhooks Reference

    Webhooks Reference

    Webhooks allow you to receive real-time notifications when events occur in Userlist. When an event happens (such as a user being created, a message being opened, or a form being submitted), Userlist sends an HTTP POST request to your configured endpoint with details about the event.

    This reference documents the structure of webhook payloads, how to verify their authenticity, and the specific events you can subscribe to.

    Setting up webhooks

    You can manage your webhook endpoints in the Webhooks Integration settings page. There, you can add new endpoints, select which events to subscribe to, and enable or disable webhook delivery.

    Request structure

    Webhooks from Userlist are sent as HTTP POST requests with a JSON payload. The payload contains information about the event that triggered the webhook. See below for a full list of webhook events and their payload structures.

    Example Webhook Payload 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

    POST /your/webhook/endpoint HTTP/1.1
Host: yourdomain.com
Content-Type: application/json; charset=utf-8
X-Userlist-Signature: t=1764846825,v1=b9a214590ebad332a83034b14527ff257ca19e97899164ef7625cbaa531c3dd8

{
  "id": "0ed1e6d0-ba8b-4194-8999-4e7fe4821a2c",
  "name": "user_updated",
  "scope": "userlist",
  "occurred_at": "2024-12-04T14:20:00Z",
  "created_at": "2024-12-04T14:20:15Z",
  "updated_at": "2024-12-04T14:20:15Z",
  "user": {
    "id": "3d70d1d4-484a-4e72-8857-916ee525214e",
    "identifier": "user-123",
    "email": "user-123@example.com",
    "properties": {
      "first_name": "Delaney",
      "last_name": "Jones"
    },
    "signed_up_at": "2024-01-15T10:30:00Z",
    "last_seen_at": "2024-12-04T14:22:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-12-04T14:22:00Z"
  }
}

    Automatic retries

    If your webhook endpoint returns an HTTP error status code (400-5xx) or fails to respond, Userlist will automatically retry delivering the webhook up to 10 times. Retries follow an exponential backoff strategy, with increasing delays between attempts to give your server time to recover.

    Your endpoint should respond with a 2xx status code to acknowledge successful receipt of the webhook. If you need to perform long-running operations in response to a webhook, consider responding immediately with a success status and processing the webhook asynchronously to avoid timeouts.

    Event ordering

    Webhook events are delivered as they occur, but the order of delivery is not guaranteed. Due to network conditions, retries, or parallel processing, events may arrive out of sequence at your endpoint.

    Verifing webhook payloads

    In order verify that incoming webhook requests are genuinely from Userlist, you can use the X-Userlist-Signature header included with each request.

    Signature Example 
    X-Userlist-Signature: t=1764843117,v1=4c72b7ab5caa24d653a065bb70ad77eaa00ad479393ec29b5839abf1fd085d53

    The signature includes a timestamp and a hash-based message authentication code (HMAC) using SHA-256. To verify the signature, start by splitting the value of the X-Userlist-Signature header by commas to get the timestamp and signature components. Then, split each component by the equals sign (=) to extract the actual values.

    Signature Format 
    X-Userlist-Signature: t=<timestamp>,v1=<hex_signature>

    Next, prepare the string to sign by concatenating the timestamp extracted from the header and the raw request body (the exact bytes received) with a period (.) in between.

    1

    "<timestamp>.<raw_request_body>"

    Then, use your webhook secret (found in the webhook configuration screen) to compute the HMAC SHA-256 hash of the prepared string.

    1

    HMAC256("<timestamp>.<raw_request_body>", webhook_secret)

    Finally, compare the computed hash (in hexadecimal format) with the signature extracted from the X-Userlist-Signature header. If they match, the webhook request is verified as coming from Userlist. To prevent replay attacks, check that the timestamp is within an acceptable time window to the current time. To prevent timing attacks, use a constant-time comparison function.

    Here are a couple of example implementations in different programming languages. Their standard libraries provide the necessary cryptographic functions to compute HMAC SHA-256 hashes.

    JavaScript (Node.js) Ruby Python PHP Elixir
    Verify Webhook Signature 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

    const crypto = require('crypto');

function verifyWebhookSignature(header, body, webhookSecret) {
  const parts = header.split(',');
  const timestamp = parts[0].split('=')[1];
  const signature = parts[1].split('=')[1];

  const signedPayload = `${timestamp}.${body}`;
  const computedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(signedPayload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(computedSignature),
    Buffer.from(signature)
  );
}

    List of webhook events

    Title Event Name
    User Created user_created
    User Updated user_updated
    User Subscribed user_subscribed
    User Unsubscribed user_unsubscribed
    Company Created company_created
    Company Updated company_updated
    Relationship Created relationship_created
    Relationship Updated relationship_updated
    Form Submitted form_submitted
    Message Enqueued message_enqueued
    Message Opened message_opened
    Message Clicked message_clicked
    Message Bounced message_bounced
    Message Reported message_reported

    User Created

    Triggered when a new user is created in Userlist.

    Properties

    Hide default properties Show default properties
    • id string

      The unique internal identifier for the event.

    • scope string

      The scope of the event. This is always userlist for events generated by Userlist itself.

    • properties object

      An object containing additional information about the event.

    • occurred_at datetime

      The timestamp (in UTC) when the event was created, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • created_at datetime

      The timestamp (in UTC) when the event was created in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • updated_at datetime

      The timestamp (in UTC) when the event was last updated in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    Example

    User Created 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

    {
  "id": "beab5c39-c043-4392-bf8c-f786203c5c69",
  "name": "user_created",
  "scope": "userlist",
  "occurred_at": "2024-12-04T14:20:00Z",
  "created_at": "2024-12-04T14:20:15Z",
  "updated_at": "2024-12-04T14:20:15Z",
  "user": {
    "id": "3d70d1d4-484a-4e72-8857-916ee525214e",
    "identifier": "user-123",
    "email": "user-123@example.com",
    "properties": {
      "first_name": "Delaney",
      "last_name": "Jones"
    },
    "signed_up_at": "2024-01-15T10:30:00Z",
    "last_seen_at": "2024-12-04T14:22:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-12-04T14:22:00Z"
  }
}

    User Updated

    Triggered when an existing user is updated in Userlist.

    Properties

    Hide default properties Show default properties
    • id string

      The unique internal identifier for the event.

    • scope string

      The scope of the event. This is always userlist for events generated by Userlist itself.

    • properties object

      An object containing additional information about the event.

    • occurred_at datetime

      The timestamp (in UTC) when the event was created, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • created_at datetime

      The timestamp (in UTC) when the event was created in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • updated_at datetime

      The timestamp (in UTC) when the event was last updated in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    Example

    User Updated 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

    {
  "id": "84d11026-54cb-4155-9bca-12846bab3ee1",
  "name": "user_updated",
  "scope": "userlist",
  "occurred_at": "2024-12-04T14:20:00Z",
  "created_at": "2024-12-04T14:20:15Z",
  "updated_at": "2024-12-04T14:20:15Z",
  "user": {
    "id": "3d70d1d4-484a-4e72-8857-916ee525214e",
    "identifier": "user-123",
    "email": "user-123@example.com",
    "properties": {
      "first_name": "Delaney",
      "last_name": "Jones"
    },
    "signed_up_at": "2024-01-15T10:30:00Z",
    "last_seen_at": "2024-12-04T14:22:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-12-04T14:22:00Z"
  }
}

    User Subscribed

    Triggered when a user subscribes to receive messages. Either globally or for a specific topic.

    Properties

    Hide default properties Show default properties
    • id string

      The unique internal identifier for the event.

    • scope string

      The scope of the event. This is always userlist for events generated by Userlist itself.

    • occurred_at datetime

      The timestamp (in UTC) when the event was created, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • created_at datetime

      The timestamp (in UTC) when the event was created in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • updated_at datetime

      The timestamp (in UTC) when the event was last updated in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    Example

    User Subscribed 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

    {
  "id": "e820ea37-0283-46af-b80e-4ca0b1b420f3",
  "name": "user_subscribed",
  "scope": "userlist",
  "occurred_at": "2024-12-04T14:20:00Z",
  "created_at": "2024-12-04T14:20:15Z",
  "updated_at": "2024-12-04T14:20:15Z",
  "user": {
    "id": "3d70d1d4-484a-4e72-8857-916ee525214e",
    "identifier": "user-123",
    "email": "user-123@example.com",
    "properties": {
      "first_name": "Delaney",
      "last_name": "Jones"
    },
    "signed_up_at": "2024-01-15T10:30:00Z",
    "last_seen_at": "2024-12-04T14:22:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-12-04T14:22:00Z"
  }
}

    User Unsubscribed

    Triggered when a user unsubscribes from receiving messages. Either globally or for a specific topic.

    Properties

    Hide default properties Show default properties
    • id string

      The unique internal identifier for the event.

    • scope string

      The scope of the event. This is always userlist for events generated by Userlist itself.

    • occurred_at datetime

      The timestamp (in UTC) when the event was created, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • created_at datetime

      The timestamp (in UTC) when the event was created in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • updated_at datetime

      The timestamp (in UTC) when the event was last updated in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    Example

    User Unsubscribed 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

    {
  "id": "92acf2e9-3ae7-4725-a0ab-c1590e5bcd3c",
  "name": "user_unsubscribed",
  "scope": "userlist",
  "occurred_at": "2024-12-04T14:20:00Z",
  "created_at": "2024-12-04T14:20:15Z",
  "updated_at": "2024-12-04T14:20:15Z",
  "user": {
    "id": "3d70d1d4-484a-4e72-8857-916ee525214e",
    "identifier": "user-123",
    "email": "user-123@example.com",
    "properties": {
      "first_name": "Delaney",
      "last_name": "Jones"
    },
    "signed_up_at": "2024-01-15T10:30:00Z",
    "last_seen_at": "2024-12-04T14:22:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-12-04T14:22:00Z"
  }
}

    Company Created

    Triggered when a new company is created in Userlist.

    Properties

    Hide default properties Show default properties
    • id string

      The unique internal identifier for the event.

    • scope string

      The scope of the event. This is always userlist for events generated by Userlist itself.

    • properties object

      An object containing additional information about the event.

    • occurred_at datetime

      The timestamp (in UTC) when the event was created, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • created_at datetime

      The timestamp (in UTC) when the event was created in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • updated_at datetime

      The timestamp (in UTC) when the event was last updated in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    Example

    Company Created 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

    {
  "id": "d16d8ad8-0f60-4f53-8fb3-ef6c160ee267",
  "name": "company_created",
  "scope": "userlist",
  "occurred_at": "2024-12-04T14:20:00Z",
  "created_at": "2024-12-04T14:20:15Z",
  "updated_at": "2024-12-04T14:20:15Z",
  "company": {
    "id": "8b4f7a23-c9d1-4e8a-9b2c-1f5a6e3d8c9b",
    "identifier": "company-567",
    "name": "Example, Inc.",
    "properties": {
      "industry": "Software",
      "billing_plan": "enterprise"
    },
    "signed_up_at": "2024-01-10T09:00:00Z",
    "created_at": "2024-01-10T09:00:00Z",
    "updated_at": "2024-12-01T11:45:00Z"
  }
}

    Company Updated

    Triggered when an existing company is updated in Userlist.

    Properties

    Hide default properties Show default properties
    • id string

      The unique internal identifier for the event.

    • scope string

      The scope of the event. This is always userlist for events generated by Userlist itself.

    • properties object

      An object containing additional information about the event.

    • occurred_at datetime

      The timestamp (in UTC) when the event was created, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • created_at datetime

      The timestamp (in UTC) when the event was created in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • updated_at datetime

      The timestamp (in UTC) when the event was last updated in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    Example

    Company Updated 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

    {
  "id": "28dccb0f-81d6-44e9-b439-531f307e2c24",
  "name": "company_updated",
  "scope": "userlist",
  "occurred_at": "2024-12-04T14:20:00Z",
  "created_at": "2024-12-04T14:20:15Z",
  "updated_at": "2024-12-04T14:20:15Z",
  "company": {
    "id": "8b4f7a23-c9d1-4e8a-9b2c-1f5a6e3d8c9b",
    "identifier": "company-567",
    "name": "Example, Inc.",
    "properties": {
      "industry": "Software",
      "billing_plan": "enterprise"
    },
    "signed_up_at": "2024-01-10T09:00:00Z",
    "created_at": "2024-01-10T09:00:00Z",
    "updated_at": "2024-12-01T11:45:00Z"
  }
}

    Relationship Created

    Triggered when a new relationship between a user and a company is created in Userlist.

    Properties

    Hide default properties Show default properties
    • id string

      The unique internal identifier for the event.

    • scope string

      The scope of the event. This is always userlist for events generated by Userlist itself.

    • properties object

      An object containing additional information about the event.

    • occurred_at datetime

      The timestamp (in UTC) when the event was created, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • created_at datetime

      The timestamp (in UTC) when the event was created in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • updated_at datetime

      The timestamp (in UTC) when the event was last updated in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    Example

    Relationship Created 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

    {
  "id": "55585414-b3b7-4e68-974f-c3a8e0b9be55",
  "name": "relationship_created",
  "scope": "userlist",
  "occurred_at": "2024-12-04T14:20:00Z",
  "created_at": "2024-12-04T14:20:15Z",
  "updated_at": "2024-12-04T14:20:15Z",
  "user": {
    "id": "3d70d1d4-484a-4e72-8857-916ee525214e",
    "identifier": "user-123",
    "email": "user-123@example.com",
    "properties": {
      "first_name": "Delaney",
      "last_name": "Jones"
    },
    "signed_up_at": "2024-01-15T10:30:00Z",
    "last_seen_at": "2024-12-04T14:22:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-12-04T14:22:00Z"
  },
  "company": {
    "id": "8b4f7a23-c9d1-4e8a-9b2c-1f5a6e3d8c9b",
    "identifier": "company-567",
    "name": "Example, Inc.",
    "properties": {
      "industry": "Software",
      "billing_plan": "enterprise"
    },
    "signed_up_at": "2024-01-10T09:00:00Z",
    "created_at": "2024-01-10T09:00:00Z",
    "updated_at": "2024-12-01T11:45:00Z"
  },
  "relationship": {
    "id": "5c7e2a91-b8f3-4d6a-a1e9-7b4c8d2f1a5e",
    "properties": { "role": "owner" },
    "created_at": "2024-01-15T10:35:00Z",
    "updated_at": "2024-11-20T16:10:00Z"
  }
}

    Relationship Updated

    Triggered when an existing relationship between a user and a company is updated in Userlist.

    Properties

    Hide default properties Show default properties
    • id string

      The unique internal identifier for the event.

    • scope string

      The scope of the event. This is always userlist for events generated by Userlist itself.

    • properties object

      An object containing additional information about the event.

    • occurred_at datetime

      The timestamp (in UTC) when the event was created, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • created_at datetime

      The timestamp (in UTC) when the event was created in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • updated_at datetime

      The timestamp (in UTC) when the event was last updated in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    Example

    Relationship Updated 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

    {
  "id": "818b17b7-1ad0-49cf-aab3-2e44a117dfcc",
  "name": "relationship_updated",
  "scope": "userlist",
  "occurred_at": "2024-12-04T14:20:00Z",
  "created_at": "2024-12-04T14:20:15Z",
  "updated_at": "2024-12-04T14:20:15Z",
  "user": {
    "id": "3d70d1d4-484a-4e72-8857-916ee525214e",
    "identifier": "user-123",
    "email": "user-123@example.com",
    "properties": {
      "first_name": "Delaney",
      "last_name": "Jones"
    },
    "signed_up_at": "2024-01-15T10:30:00Z",
    "last_seen_at": "2024-12-04T14:22:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-12-04T14:22:00Z"
  },
  "company": {
    "id": "8b4f7a23-c9d1-4e8a-9b2c-1f5a6e3d8c9b",
    "identifier": "company-567",
    "name": "Example, Inc.",
    "properties": {
      "industry": "Software",
      "billing_plan": "enterprise"
    },
    "signed_up_at": "2024-01-10T09:00:00Z",
    "created_at": "2024-01-10T09:00:00Z",
    "updated_at": "2024-12-01T11:45:00Z"
  },
  "relationship": {
    "id": "5c7e2a91-b8f3-4d6a-a1e9-7b4c8d2f1a5e",
    "properties": { "role": "owner" },
    "created_at": "2024-01-15T10:35:00Z",
    "updated_at": "2024-11-20T16:10:00Z"
  }
}

    Form Submitted

    Triggered when a user submits a form.

    Properties

    Hide default properties Show default properties
    • id string

      The unique internal identifier for the event.

    • scope string

      The scope of the event. This is always userlist for events generated by Userlist itself.

    • properties object

      An object containing additional information about the event.

    • occurred_at datetime

      The timestamp (in UTC) when the event was created, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • created_at datetime

      The timestamp (in UTC) when the event was created in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • updated_at datetime

      The timestamp (in UTC) when the event was last updated in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    Example

    Form Submitted 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

    {
  "id": "9a8ee05a-b038-4a56-bf9c-42fbafddace4",
  "name": "form_submitted",
  "scope": "userlist",
  "occurred_at": "2024-12-04T14:20:00Z",
  "created_at": "2024-12-04T14:20:15Z",
  "updated_at": "2024-12-04T14:20:15Z",
  "user": {
    "id": "3d70d1d4-484a-4e72-8857-916ee525214e",
    "identifier": "user-123",
    "email": "user-123@example.com",
    "properties": {
      "first_name": "Delaney",
      "last_name": "Jones"
    },
    "signed_up_at": "2024-01-15T10:30:00Z",
    "last_seen_at": "2024-12-04T14:22:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-12-04T14:22:00Z"
  }
}

    Message Enqueued

    Triggered when a message is enqueued to be sent to a user.

    Properties

    Hide default properties Show default properties
    • id string

      The unique internal identifier for the event.

    • scope string

      The scope of the event. This is always userlist for events generated by Userlist itself.

    • occurred_at datetime

      The timestamp (in UTC) when the event was created, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • created_at datetime

      The timestamp (in UTC) when the event was created in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • updated_at datetime

      The timestamp (in UTC) when the event was last updated in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    Example

    Message Enqueued 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

    {
  "id": "52763388-e4d3-41ce-b1bd-4e40771770aa",
  "name": "message_enqueued",
  "scope": "userlist",
  "occurred_at": "2024-12-04T14:20:00Z",
  "created_at": "2024-12-04T14:20:15Z",
  "updated_at": "2024-12-04T14:20:15Z",
  "properties": {
    "message_id": "019eff22-ab1d-7ba2-854e-5d32fae11e60",
    "subject": "Welcome to Userlist!"
  },
  "user": {
    "id": "3d70d1d4-484a-4e72-8857-916ee525214e",
    "identifier": "user-123",
    "email": "user-123@example.com",
    "properties": {
      "first_name": "Delaney",
      "last_name": "Jones"
    },
    "signed_up_at": "2024-01-15T10:30:00Z",
    "last_seen_at": "2024-12-04T14:22:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-12-04T14:22:00Z"
  }
}

    Message Opened

    Triggered when a user opens a message.

    Properties

    Hide default properties Show default properties
    • id string

      The unique internal identifier for the event.

    • scope string

      The scope of the event. This is always userlist for events generated by Userlist itself.

    • occurred_at datetime

      The timestamp (in UTC) when the event was created, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • created_at datetime

      The timestamp (in UTC) when the event was created in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • updated_at datetime

      The timestamp (in UTC) when the event was last updated in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    Example

    Message Opened 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

    {
  "id": "13cc78e1-3cfa-4fd0-a968-83e9e5d9fa93",
  "name": "message_opened",
  "scope": "userlist",
  "occurred_at": "2024-12-04T14:20:00Z",
  "created_at": "2024-12-04T14:20:15Z",
  "updated_at": "2024-12-04T14:20:15Z",
  "properties": {
    "message_id": "019eff22-ab1d-7ba2-854e-5d32fae11e60",
    "subject": "Welcome to Userlist!"
  },
  "user": {
    "id": "3d70d1d4-484a-4e72-8857-916ee525214e",
    "identifier": "user-123",
    "email": "user-123@example.com",
    "properties": {
      "first_name": "Delaney",
      "last_name": "Jones"
    },
    "signed_up_at": "2024-01-15T10:30:00Z",
    "last_seen_at": "2024-12-04T14:22:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-12-04T14:22:00Z"
  }
}

    Message Clicked

    Triggered when a user clicks a link in a message.

    Properties

    Hide default properties Show default properties
    • id string

      The unique internal identifier for the event.

    • scope string

      The scope of the event. This is always userlist for events generated by Userlist itself.

    • occurred_at datetime

      The timestamp (in UTC) when the event was created, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • created_at datetime

      The timestamp (in UTC) when the event was created in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • updated_at datetime

      The timestamp (in UTC) when the event was last updated in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    Example

    Message Clicked 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

    {
  "id": "dc156d69-a4ec-4758-84fc-2130828c733d",
  "name": "message_clicked",
  "scope": "userlist",
  "occurred_at": "2024-12-04T14:20:00Z",
  "created_at": "2024-12-04T14:20:15Z",
  "updated_at": "2024-12-04T14:20:15Z",
  "properties": {
    "message_id": "019eff22-ab1d-7ba2-854e-5d32fae11e60",
    "subject": "Welcome to Userlist!",
    "url": "https://userlist.com/"
  },
  "user": {
    "id": "3d70d1d4-484a-4e72-8857-916ee525214e",
    "identifier": "user-123",
    "email": "user-123@example.com",
    "properties": {
      "first_name": "Delaney",
      "last_name": "Jones"
    },
    "signed_up_at": "2024-01-15T10:30:00Z",
    "last_seen_at": "2024-12-04T14:22:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-12-04T14:22:00Z"
  }
}

    Message Bounced

    Triggered when an email to a user bounces.

    Properties

    Hide default properties Show default properties
    • id string

      The unique internal identifier for the event.

    • scope string

      The scope of the event. This is always userlist for events generated by Userlist itself.

    • occurred_at datetime

      The timestamp (in UTC) when the event was created, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • created_at datetime

      The timestamp (in UTC) when the event was created in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • updated_at datetime

      The timestamp (in UTC) when the event was last updated in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    Example

    Message Bounced 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

    {
  "id": "1e76a94f-28c5-47c8-b012-3d57b4bc5f76",
  "name": "message_bounced",
  "scope": "userlist",
  "occurred_at": "2024-12-04T14:20:00Z",
  "created_at": "2024-12-04T14:20:15Z",
  "updated_at": "2024-12-04T14:20:15Z",
  "properties": {
    "message_id": "019eff22-ab1d-7ba2-854e-5d32fae11e60",
    "subject": "Welcome to Userlist!",
    "bounce_type": "permanent",
    "bounce_reason": "The email address does not exist."
  },
  "user": {
    "id": "3d70d1d4-484a-4e72-8857-916ee525214e",
    "identifier": "user-123",
    "email": "user-123@example.com",
    "properties": {
      "first_name": "Delaney",
      "last_name": "Jones"
    },
    "signed_up_at": "2024-01-15T10:30:00Z",
    "last_seen_at": "2024-12-04T14:22:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-12-04T14:22:00Z"
  }
}

    Message Reported

    Triggered when a user marks a message as spam via their email provider. Please note that not all email providers support this feature.

    Properties

    Hide default properties Show default properties
    • id string

      The unique internal identifier for the event.

    • scope string

      The scope of the event. This is always userlist for events generated by Userlist itself.

    • occurred_at datetime

      The timestamp (in UTC) when the event was created, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • created_at datetime

      The timestamp (in UTC) when the event was created in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    • updated_at datetime

      The timestamp (in UTC) when the event was last updated in Userlist, formatted as YYYY-MM-DDTHH:MM:SSZ (RFC3339/ISO8601)

    Example

    Message Reported 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

    {
  "id": "3b87fc95-5c4f-4e75-aaac-f10797384234",
  "name": "message_reported",
  "scope": "userlist",
  "occurred_at": "2024-12-04T14:20:00Z",
  "created_at": "2024-12-04T14:20:15Z",
  "updated_at": "2024-12-04T14:20:15Z",
  "properties": {
    "message_id": "019eff22-ab1d-7ba2-854e-5d32fae11e60",
    "subject": "Welcome to Userlist!"
  },
  "user": {
    "id": "3d70d1d4-484a-4e72-8857-916ee525214e",
    "identifier": "user-123",
    "email": "user-123@example.com",
    "properties": {
      "first_name": "Delaney",
      "last_name": "Jones"
    },
    "signed_up_at": "2024-01-15T10:30:00Z",
    "last_seen_at": "2024-12-04T14:22:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-12-04T14:22:00Z"
  }
}
    Related Articles
    Have questions? Contact us at support@userlist.com anytime.
    []

    Book your discovery demo

    Lets see how Userlist fits into the bigger picture of your SaaS business. Youll learn about our automation features, integrations, proven lifecycle frameworks, and how we can help you hit your SaaS growth targets.

    Book a demo call
    • Product
    Resources Switching From
    Our Podcasts Legal
    Summary

    Ask AI for a summary of Userlist

    Contact Us Userlist, Inc.
    6595 Roswell Road, STE G2130
    Atlanta, GA 30328 USA
    +1 470 220 7227

    Helping SaaS companies with email marketing automation since 2017.

    We contribute 1% of all revenue to Stripe Climate to remove CO from the atmosphere.

    Web Proxy Viewer  |  New URL  |  Original Page